react-semaphor 0.1.545 → 0.1.547

package/dist/types/shared/dashboard-authoring/filter-applicability.d.ts

@@ -0,0 +1,75 @@
+import { SemaphorSkippedConstraintReason } from '../analytics-protocol/index.js';
+import { TFilterValue } from '../../components/surfboard/filter/types.js';
+import { TCard } from '../../lib/types/common-types.js';
+import { CardConfig, DataSource } from '../../lib/types/explorer-types.js';
+/**
+ * Whether a dashboard filter's value applies to a card: the one rule (MCP
+ * dashboard editing ledger V-44). The query builder runs it on every filter
+ * value a card receives (semaphor-app build-query); the dashboard's filter
+ * mapping decision (`decideDashboardFilterCardTarget`) and every description
+ * of reach (the outline, reach warnings, the change resolver's effect check)
+ * read it too, so a filter reaches the same cards whether or not it has card
+ * mappings. Moved unchanged from semaphor-app
+ * `src/lib/analytics/query/filter-applicability.ts`, which re-exports it.
+ */
+/** The protocol's skip reasons: evidence reports them as they are (D3b-4). */
+export type FilterSkipReason = SemaphorSkippedConstraintReason;
+export type SkippedFilter = {
+    filterId?: string;
+    name?: string;
+    reason: FilterSkipReason;
+    details?: string;
+};
+export declare function formatSkippedFilterWarnings(skipped: ReadonlyArray<{
+    filterId?: string;
+    name?: string;
+    reason: string;
+}>): string[];
+export type FilterApplicabilityResult = {
+    applicableFilters: TFilterValue[];
+    skippedFilters: SkippedFilter[];
+};
+export type FilterApplicabilityPhase = 'pre_join' | 'post_join';
+export type FilterApplicabilityContext = {
+    cardDataSource?: DataSource | null;
+    targetQualifiedTableName?: string;
+    allowCalculated?: boolean;
+    additionalAllowedIdentifiers?: string[];
+    phase?: FilterApplicabilityPhase;
+};
+/** The same explicit join sources participate in early and final applicability. */
+export declare function collectJoinPlanIdentifiers(joinPlan: CardConfig['joinPlan'] | null): string[];
+/** Only for physical cards after structural completeness validation. Semantic
+ * cards need current catalog dependencies before deciding applicability. Keep
+ * unknown or partially overlapping predicates for the authoritative path. */
+export declare function pruneUnrelatedCalculatedFilters(filters: TFilterValue[], context: FilterApplicabilityContext): FilterApplicabilityResult;
+/**
+ * How the rule decides one filter value: applied with dataset proof, applied
+ * without it (no datasets to check against, a legacy unqualified name, a
+ * calculation with unknown dependencies), or skipped with a reason.
+ */
+export type FilterApplicabilityDecision = {
+    kind: 'apply';
+    proven: boolean;
+} | {
+    kind: 'skip';
+    reason: FilterSkipReason;
+    details?: string;
+};
+export declare function applyFilterApplicability(activeFilters: TFilterValue[] | undefined, context: FilterApplicabilityContext): FilterApplicabilityResult;
+/**
+ * The applicability context of a card as the query builder runs it: the
+ * card's data source, its join plan's entities, and the join phase.
+ */
+export declare function filterApplicabilityContextForCard(card: {
+    dataSource?: DataSource | null;
+    joinPlan?: CardConfig['joinPlan'] | null;
+}): FilterApplicabilityContext;
+/**
+ * Whether a filter value reaches a saved card, by the one rule: `reachable`
+ * when the card's data (the datasets it selects or joins) proves it takes the
+ * value's field, `unreachable` when the rule skips it, `unknown` when the rule
+ * keeps it without proof (nothing to check against, a legacy unqualified
+ * name, a calculation with unknown dependencies).
+ */
+export declare function filterValueReachForCard(filterValue: TFilterValue, card: Pick<TCard, 'dataSource' | 'config'>): 'reachable' | 'unreachable' | 'unknown';

package/dist/types/shared/dashboard-authoring/filter-reach-copy.d.ts

@@ -0,0 +1,18 @@
+import { SemaphorRelationshipRoute, SemaphorSkippedConstraintReason } from '../analytics-protocol/index.js';
+/** "Project" to "Projects", "Category" to "Categories"; a label ending in "s" stays. */
+export declare function pluralDatasetLabel(label: string): string;
+/**
+ * P-8 and P-11: "through Project" for a to-one route; "Projects with at least
+ * one matching Dashboard" for a to-many route, where Dashboard is the dataset
+ * its first to-many step reaches. A route of more than one step names the
+ * datasets it passes through, not the filter's own, which it always ends at
+ * ("through Crew" for a Company filter; ledger R-21).
+ */
+export declare function describeRelationshipRoute(route: SemaphorRelationshipRoute): string;
+/** P-1: a persisted route the domain no longer has. */
+export declare const RELATIONSHIP_ROUTE_CHANGED_MESSAGE = "The relationship this card used changed; choose it again";
+/** P-2, P-3, P-6, P-7: why a value was not applied to a card. */
+export declare function describeRelationshipSkip(reason: SemaphorSkippedConstraintReason, cardDataset?: {
+    name: string;
+    label?: string;
+}): string;

package/dist/types/shared/dashboard-authoring/filter-reach-preview.d.ts

@@ -0,0 +1,97 @@
+import { SemaphorRelationshipRoute, SemaphorSkippedConstraintReason } from '../analytics-protocol/index.js';
+import { TFilter } from '../../components/surfboard/filter/types.js';
+import { DashboardFilterOptionSource, DashboardFilterRelationshipTarget } from './dashboard-filter-mapping-types.js';
+/**
+ * The Cards tab's relationship preview (relationship filter reach, Phase 3):
+ * `POST /api/v1/filter-reach` resolves each in-scope card the way its query
+ * will, without a value. Authoring only, never on the card query path.
+ */
+export type FilterReachRequest = {
+    dashboardId: string;
+    /** The filter as staged in the settings popover (unsaved edits included). */
+    filter: TFilter;
+    /** The draft's Option Source; absent when the draft has none (ledger R-04). */
+    optionSource?: DashboardFilterOptionSource;
+    /** In-scope cards, each as the draft runs it. */
+    cards: FilterReachPreviewCard[];
+};
+/** A card to preview, with the route the draft runs it with (ledger R-02). */
+export type FilterReachPreviewCard = {
+    cardId: string;
+    /**
+     * The card's chosen route as the draft stands (RF-D10): a staged choice,
+     * else the saved one unless the author dropped it. Absent: the card has no
+     * entry of its own, and the preview says what the domain's relationships do.
+     */
+    target?: DashboardFilterRelationshipTarget;
+};
+/**
+ * What the domain's relationships do for a card as the draft runs it
+ * (relationship filter reach S-D).
+ */
+export type FilterReachCardOutcome = {
+    status: 'applied';
+    route: SemaphorRelationshipRoute;
+} | {
+    status: 'skipped';
+    reason: SemaphorSkippedConstraintReason;
+}
+/** More than one equally preferred path: the card skips the filter until one is chosen (P-7). */
+ | {
+    status: 'needsPath';
+} | {
+    status: 'blocked';
+    message: string;
+}
+/**
+ * The card applies the value as one of its own filters: the value's dataset
+ * is one its query already uses (its own filters included), so no route is
+ * needed (ledger R-05).
+ */
+ | {
+    status: 'kept';
+}
+/** Reached another way, or not a semantic auto-join card. */
+ | {
+    status: 'notRelationship';
+};
+/**
+ * One card's preview: the outcome for the decision it answers, and the
+ * card's paths. A reader shows the outcome only while the card's decision is
+ * still the one named in `answers` (RF-INV-15); the paths don't depend on the
+ * decision (RF-D27).
+ */
+export type FilterReachCardPreview = {
+    cardId: string;
+    /** The decision this outcome is for: the path ids the request carried for the card, or none. */
+    answers: {
+        relationshipIds?: string[];
+    };
+    outcome: FilterReachCardOutcome;
+    /** The card's equally preferred paths, worked out with no path chosen; empty without a tie. */
+    paths: FilterReachPathOption[];
+};
+/**
+ * One path an author can choose, with the target that saves it: built by the
+ * server from the filter's value field in the card's domain, never from the
+ * browser's guess of that field (ledger R-16).
+ */
+export type FilterReachPathOption = {
+    route: SemaphorRelationshipRoute;
+    target: DashboardFilterRelationshipTarget;
+};
+export type FilterReachResponse = {
+    previews: FilterReachCardPreview[];
+    /** Present only when the caller can edit the domain the routes run in. */
+    manageRelationships?: {
+        href: string;
+    };
+};
+/** Whether a preview answers a card's decision as it stands: the same path, or no path for both (RF-INV-15). */
+export declare function filterReachPreviewAnswers(preview: Pick<FilterReachCardPreview, 'answers'>, relationshipIds: readonly string[] | undefined): boolean;
+/**
+ * Reads a `/api/v1/filter-reach` response body. A malformed preview is
+ * dropped whole: one with no decision it answers, an unknown outcome, a
+ * malformed path, or a tie with fewer than two paths.
+ */
+export declare function readFilterReachResponse(body: unknown): FilterReachResponse;

package/dist/types/shared/dashboard-authoring/index.d.ts

@@ -2,9 +2,7 @@ export * from './contracts.js';
 export * from './comparison-document-migration.js';
 export * from './source-matching.js';
 export * from './validators.js';
-export * from './layout-compiler.js';
 export * from './artifact-compiler.js';
-export * from './change-compiler.js';
 export * from './protocol-adapter.js';
 export * from './temporal-result-owner.js';
 export * from './temporal-bucket-authoring.js';
@@ -39,3 +37,25 @@ export { matrixCatalogSources, matrixExecutionSources } from './matrix-control-s
 export * from './dashboard-option-dependencies.js';
 export * from './new-card.js';
 export * from './operations/apply-dashboard-operations.js';
+export * from './changes/card-types.js';
+export * from './changes/diagnostics.js';
+export * from './changes/card-query-part.js';
+export * from './changes/read-card-query.js';
+export * from './changes/dashboard-change.js';
+export * from './changes/resolve-dashboard-changes.js';
+export * from './outline/outline-filters.js';
+export * from './outline/outline-dashboard.js';
+export * from './column-catalog.js';
+export { prepareLoadedDashboard } from '../../lib/dashboard-inputs/prepare-loaded-dashboard.js';
+export { buildFilterInputFromField, buildFilterInputFromDefinition, applyFilterSettingsChange } from '../../lib/dashboard-inputs/filter-settings.js';
+export { relationshipRouteTarget } from '../../lib/dashboard-inputs/dashboard-filter-value-identity.js';
+export type { FilterSettingsChange, FilterValueEffect } from '../../lib/dashboard-inputs/filter-settings.js';
+export { describeDashboardFilterCardReach, describeDashboardFilterCardReachDetail, type DashboardFilterCardReach, type DashboardFilterCardReachDetail, type DashboardRelationshipReachResolver, } from '../../lib/query-context/dashboard-filter-mapping-resolution.js';
+export { changeCardType, sharedCardPreferences, type CardTypeChange, type CardTypeChangeOptions, } from '../../lib/utils/card-type-change.js';
+export { buildSavedEditorCard } from '../../lib/utils/build-saved-editor-card.js';
+export { getCardDefinition, type AuthoredCardFields } from '../../lib/utils/card-definition.js';
+export { changeMatrixEditor, dropMatrixEditorField, matrixEditorCatalogFromFields, } from '../../lib/matrix-table/matrix-editor.js';
+export * from './filter-applicability.js';
+export * from './semantic-auto-join-card.js';
+export * from './filter-reach-preview.js';
+export * from './filter-reach-copy.js';

package/dist/types/shared/dashboard-authoring/operations/apply-dashboard-operations.d.ts

@@ -1,40 +1,13 @@
-import { TDashboard, TFrame } from '../../../lib/types/common-types.js';
+import { TDashboard } from '../../../lib/types/common-types.js';
+import { DashboardOperation, DashboardOperationResult, OperationContext } from './operation-types.js';
+export type { CardUpdate, CreatedEntity, DashboardOperation, DashboardOperationResult, DashboardRuntimeEffect, FrameCommit, FramePlacement, OperationContext, OperationDescription, OperationFailureCode, } from './operation-types.js';
 /**
  * Edits to a dashboard as operations on one pure reducer (analytics agent
- * Plan 1, AG-D14, Phase 7a). Every writer of these edits calls it: the
- * store's actions in the browser, and later an API or MCP edit on the
- * server. Callers that differ pass their differences in (placement, ids);
- * none keeps its own copy of the edit.
+ * Plan 1 AG-D14; MCP dashboard editing SPEC 3.3, 3.8). The one writer of the
+ * saved document for these edits: the editor stores, the change resolver's
+ * dry run and the server's apply all call it. It writes only the document; it
+ * returns what it created, one plain sentence per change, and the runtime
+ * effects a live editor applies to its own state (DE-D49). It never mints ids
+ * and never reads the clock (S-INV-1).
  */
-/** Where a new frame goes on its sheet: first, last, or right after a frame and beside it. */
-export type DashboardFramePlacement = 'start' | 'end' | {
-    beside: string;
-};
-export type DashboardOperation = {
-    op: 'frame.add';
-    sheetId: string;
-    /** The frame with its cards, ids included. */
-    frame: TFrame;
-    /** Default `end`. */
-    placement?: DashboardFramePlacement;
-};
-export type DashboardOperationFailureCode = 'sheet_not_found'
-/** A document sheet places cards through its document, not its grid. */
- | 'sheet_not_a_grid' | 'frame_id_taken';
-export type DashboardOperationResult = {
-    ok: true;
-    dashboard: TDashboard;
-} | {
-    ok: false;
-    failedAt: {
-        index: number;
-        op: DashboardOperation['op'];
-        code: DashboardOperationFailureCode;
-        message: string;
-    };
-};
-/**
- * Applies the operations in order, all or nothing. Never changes its input:
- * the result shares every sheet it did not touch.
- */
-export declare function applyDashboardOperations(dashboard: TDashboard, operations: DashboardOperation[]): DashboardOperationResult;
+export declare function applyDashboardOperations(dashboard: TDashboard, operations: readonly DashboardOperation[], context: OperationContext): DashboardOperationResult;

package/dist/types/shared/dashboard-authoring/operations/operation-types.d.ts

@@ -0,0 +1,189 @@
+import { EmbeddedFilterDashboardInput, TDashboard, TFrame } from '../../../lib/types/common-types.js';
+import { FilterSettingsChange, FilterValueEffect } from '../../../lib/dashboard-inputs/filter-settings.js';
+import { DashboardFilterBoundCardApplication } from '../dashboard-filter-mapping-types.js';
+import { Field } from '../../../lib/types/explorer-types.js';
+import { TChartType } from '../../../lib/charts/types.js';
+import { CalendarContext } from '../../report-runtime-context/index.js';
+import { CardQueryPart, StatedLabel } from '../changes/card-query-part.js';
+import { FramePlacement } from '../../layouts/index.js';
+/**
+ * The resolved operations the dashboard reducer applies (MCP dashboard
+ * editing SPEC 3.3, 3.8). Every id an operation creates is in it; the reducer
+ * never generates ids and never reads the clock (S-INV-1).
+ */
+/** Where a new frame goes on its sheet, by intent (responsive layouts SPEC §2.4). Absent: placed by kind. */
+export type { FramePlacement };
+export type CardUpdate = 
+/** Inline title and description edits; `description: null` removes it. */
+{
+    kind: 'rename';
+    title?: string;
+    description?: string | null;
+}
+/**
+ * A type transition: the editor's `changeCardType`, then the layout resize.
+ * `catalog` is the loaded column catalog a Matrix crossing needs; `newIds`
+ * every id the conversion mints, in the order it asks for them (DE-D54).
+ */
+ | {
+    kind: 'retype';
+    type: TChartType;
+    catalog?: readonly Field[];
+    newIds: string[];
+}
+/** A new computed part for the card's current type; presentation is carried (SPEC 3.4). */
+ | {
+    kind: 'requery';
+    query: CardQueryPart;
+}
+/** Labels a change states on columns it doesn't rebuild, set in place by the label owner; nothing is recompiled (DE-D61). */
+ | {
+    kind: 'relabel';
+    labels: StatedLabel[];
+};
+/** Everything the editor's "Done", Save & Apply and Apply Local commit persists, as one operation (DE-D13). */
+export type FrameCommit = {
+    sheetId: string;
+    /** The edited frame as the editor built it. Apply Local passes `visualId: undefined`. */
+    frame: TFrame;
+    /** Other frames on the sheet rewritten during the edit (calculated-field renames), applied with it. */
+    rewrittenFrames?: TFrame[];
+    /** Sheet calculated fields from the edited frame, persisted on the sheet. */
+    sheetCalculatedFields?: Field[];
+    /** Dashboard calculated fields rewritten during the edit. */
+    dashboardCalculatedFields?: Field[];
+    /** True when committed from the visual editor: resize the frame's layouts if its type changed. */
+    resizeLayouts: boolean;
+};
+export type DashboardOperation = ({
+    op: 'card.add';
+    sheetId: string;
+    /** The frame with its cards, ids included. */
+    frame: TFrame;
+    /** By intent; absent: placed by kind (responsive layouts SPEC §4.2). */
+    placement?: FramePlacement;
+} | {
+    op: 'card.update';
+    cardId: string;
+    update: CardUpdate;
+} | {
+    op: 'card.remove';
+    cardId: string;
+}
+/** Arrange a grid sheet by kind (responsive layouts RL-D7, SPEC §4.4); `keepOrder` keeps the reading order. */
+ | {
+    op: 'layout.arrange';
+    sheetId: string;
+    keepOrder?: boolean;
+}
+/** The editor's whole-frame commit; never produced by the resolver. */
+ | {
+    op: 'frame.commit';
+    commit: FrameCommit;
+}
+/** A new filter input, ids included; its defaults are in its definition, as the editor adds one. */
+ | {
+    op: 'filter.add';
+    input: EmbeddedFilterDashboardInput;
+}
+/** Settings through the editor's core (`applyFilterSettingsChange`); `filterId` is the input id. */
+ | {
+    op: 'filter.update';
+    filterId: string;
+    settings: FilterSettingsChange;
+} | {
+    op: 'filter.remove';
+    filterId: string;
+}
+/** The card's bound entry in the filter's mapping, built as the mapping editor builds one. */
+ | {
+    op: 'filter.bind';
+    filterId: string;
+    cardId: string;
+    binding: DashboardFilterBoundCardApplication;
+} | {
+    op: 'filter.exclude';
+    filterId: string;
+    cardId: string;
+}) & {
+    /** Set by the resolver: the public change this operation came from. Descriptions group by it. */
+    changeIndex?: number;
+};
+export type OperationContext = {
+    /** The report calendar; filter defaults resolve in it. A proposal's has a fixed anchor (DE-D59). */
+    calendar: CalendarContext | null;
+};
+export type CreatedEntity = {
+    kind: 'card' | 'filter';
+    id: string;
+    title: string;
+    changeIndex?: number;
+};
+export type OperationDescription = {
+    /** Operations with the same changeIndex share one description. */
+    changeIndex?: number;
+    /** Indexes into the operations list. */
+    operations: number[];
+    sentence: string;
+};
+/** What a live editor must do to its own state after an operation. The server ignores them (DE-D49). */
+export type DashboardRuntimeEffect = 
+/** card.remove, and frame.commit dropping tabs: drop live state keyed by these cards. */
+{
+    kind: 'cards_removed';
+    cardIds: string[];
+}
+/** frame.commit: re-sync inline filter runtime values from the frame before and after. */
+ | {
+    kind: 'frame_committed';
+    sheetId: string;
+    before: TFrame;
+    after: TFrame;
+}
+/**
+ * filter.update: `applyFilterSettingsChange`'s value effects, unchanged. One
+ * per update, even with none: the store still re-resolves forced selections,
+ * as `saveFilterSettings` always has (ledger P3-02).
+ */
+ | {
+    kind: 'filter_value';
+    effects: FilterValueEffect[];
+}
+/** filter.remove: drop the input's live values. */
+ | {
+    kind: 'input_removed';
+    inputId: string;
+};
+export type OperationFailureCode = 'sheet_not_found'
+/** A document sheet places cards through its document, not its grid. */
+ | 'sheet_not_a_grid' | 'frame_id_taken' | 'frame_not_found' | 'card_not_found' | 'filter_not_found' | 'filter_id_taken'
+/** The filter settings or mapping fail the input contract; `details.issues` has the core's issues. */
+ | 'filter_invalid'
+/** A requery part compiled for another type than the card's. */
+ | 'query_type_mismatch'
+/** A requery part that doesn't make a valid card (a Matrix definition the Matrix contract refuses). */
+ | 'query_invalid'
+/** A requery would change a part of the card its change doesn't state (DE-D61). */
+ | 'query_not_kept'
+/** A conversion asked for more ids than the operation carries. */
+ | 'ids_exhausted'
+/** A retype across the Matrix boundary without a catalog. */
+ | 'catalog_loading';
+export type DashboardOperationResult = {
+    ok: true;
+    dashboard: TDashboard;
+    created: CreatedEntity[];
+    /** One plain sentence per public change (or per operation without a changeIndex). */
+    descriptions: OperationDescription[];
+    runtimeEffects: DashboardRuntimeEffect[];
+} | {
+    ok: false;
+    failedAt: {
+        index: number;
+        op: DashboardOperation['op'];
+        code: OperationFailureCode;
+        message: string;
+        fix?: string;
+        details?: Record<string, unknown>;
+    };
+};

package/dist/types/shared/dashboard-authoring/outline/outline-dashboard.d.ts

@@ -0,0 +1,101 @@
+import { DashboardRelationshipReachResolver } from '../../../lib/query-context/dashboard-filter-mapping-resolution.js';
+import { TDashboard } from '../../../lib/types/common-types.js';
+import { FrameWidth } from '../../layouts/index.js';
+import { NotEditableReason, OutlineCardSource } from '../changes/read-card-query.js';
+import { CardQuery, MatrixColumns } from '../changes/dashboard-change.js';
+import { OutlineFilter } from './outline-filters.js';
+import { CalendarContext } from '../../report-runtime-context/index.js';
+/**
+ * A dashboard in the change vocabulary (MCP dashboard editing SPEC 3.6,
+ * DE-D29, DE-D34): every sheet, every card the shared traversal lists
+ * (Document-section cards included, read only), every filter, and what the
+ * viewer may do. A pure function of the hydrated dashboard and the viewer
+ * (S-INV-8): no clock, no catalog, no network.
+ */
+export type OutlineViewer = {
+    dashboardId: string;
+    /** `Dashboard.updatedAt`, ISO 8601; the staleness token, never called "version" (DE-D37). */
+    updatedAt: string;
+    access: {
+        canEdit: boolean;
+        canCopy: boolean;
+    };
+    sql: boolean;
+    sheetIds?: string[];
+    cardIds?: string[];
+    /** Above this many cards (after narrowing), queries are left out. Default 50 (DE-D34). */
+    maxQueryCards?: number;
+    /** The report calendar filter defaults are read in; without one, a fixed calendar at `updatedAt` (S-INV-8). */
+    calendar?: CalendarContext;
+    /**
+     * Server side only: resolves relationship reach the way the card query
+     * does, with each card's domain preloaded (relationship filter reach RF-D15).
+     * Without one, such cards are listed under `relationshipPending`.
+     */
+    relationshipReach?: DashboardRelationshipReachResolver;
+};
+export type OutlineCard = {
+    cardId: string;
+    title: string;
+    /** The public type name (DE-D43). */
+    type: string;
+    source: OutlineCardSource;
+    /** Shows a library visual; changing it makes it local (DE-D50). */
+    linkedVisualId?: string;
+    editable: true;
+    /** Absent only when the outline is truncated. */
+    query?: CardQuery;
+    matrix?: MatrixColumns;
+} | {
+    cardId: string;
+    title: string;
+    type: string;
+    source?: OutlineCardSource;
+    linkedVisualId?: string;
+    editable: false;
+    notEditable: {
+        reason: NotEditableReason;
+        message: string;
+        detail?: string;
+    };
+};
+export type OutlineSheet = {
+    sheetId: string;
+    title: string;
+    /** Cards can be added only to "dashboard" sheets. */
+    kind: 'dashboard' | 'document';
+    /** On a Document sheet, its sections' cards (never editable). */
+    cards: OutlineCard[];
+    /**
+     * Grid sheets only: the desktop layout as rows, top to bottom, from the
+     * layout engine (responsive layouts RL-D10). Always the whole sheet, even
+     * when `cardIds` narrows the cards. Absent on Document sheets.
+     */
+    layout?: OutlineLayoutRow[];
+};
+/** One row of a sheet's desktop layout. A tile is a frame: its cards, active first, and its width by intent. Never coordinates (RL-INV-5). */
+export type OutlineLayoutRow = {
+    tiles: Array<{
+        cardIds: string[];
+        width: FrameWidth;
+    }>;
+};
+export type DashboardOutline = {
+    dashboardId: string;
+    title: string;
+    updatedAt: string;
+    access: {
+        canEdit: boolean;
+        canCopy: boolean;
+    };
+    /** Every dataset a card or filter uses. */
+    datasets: Array<{
+        domainId: string;
+        datasetName: string;
+    }>;
+    sheets: OutlineSheet[];
+    filters: OutlineFilter[];
+    /** Queries left out because the dashboard has more than `maxQueryCards` cards (DE-D34). */
+    truncated?: true;
+};
+export declare function outlineDashboard(dashboard: TDashboard, viewer: OutlineViewer): DashboardOutline;

package/dist/types/shared/dashboard-authoring/outline/outline-filters.d.ts

@@ -0,0 +1,100 @@
+import { TDashboard } from '../../../lib/types/common-types.js';
+import { DashboardRelationshipReachResolver } from '../../../lib/query-context/dashboard-filter-mapping-resolution.js';
+import { SemaphorSkippedConstraintReason } from '../../analytics-protocol/index.js';
+import { FilterInputEntry } from '../filter-model/index.js';
+import { CalendarContext } from '../../report-runtime-context/index.js';
+import { FilterValue, TimeWindow } from '../changes/dashboard-change.js';
+/**
+ * Every dashboard filter in the change vocabulary (MCP dashboard editing
+ * DE-D58, SPEC 3.6). A field filter on one semantic dataset shown on every
+ * grid sheet or a list of sheets is editable; any other filter is a
+ * read-only summary with its reach and a reason, never left out and never
+ * given invented coordinates. Reach is read the way each card runs the
+ * filter (`describeDashboardFilterCardReach`).
+ */
+export type FilterNotEditableReason = 'global_date' | 'not_semantic' | 'scope_not_expressible';
+export type OutlineFilter = {
+    filterId: string;
+    label: string;
+    editable: true;
+    domainId: string;
+    datasetName: string;
+    field: string;
+    selection: 'single' | 'multiple';
+    /** The values it loads with, read through the default owner (a saved default first, else the definition). */
+    defaultValues?: FilterValue[];
+    /** The window it loads with, only when the loaded default keeps one (a day picker clamps a wider window to a day). */
+    defaultPeriod?: TimeWindow;
+    /** For a date filter, the picker a viewer gets: one day, one month, or a range. */
+    datePicker?: 'day' | 'month' | 'range';
+    /** "all": every grid sheet. */
+    sheetIds: string[] | 'all';
+    /** With "all": the sheets it leaves out ("every sheet except"); a sheet added later is reached. */
+    exceptSheetIds?: string[];
+    /** With "all": it also shows on Document sheets (their sections' cards). */
+    includesDocumentSheets?: true;
+    /** Card ids the filter applies to. */
+    reaches: string[];
+    /** Card ids excluded explicitly. */
+    excluded: string[];
+    /** In scope, not matched; with a resolver (server side), the reason relationship reach gave. */
+    notReached: Array<{
+        cardId: string;
+        title: string;
+        datasetName?: string;
+        reason?: SemaphorSkippedConstraintReason;
+    }>;
+    /** In scope, and blocked when the filter has a value: a binding the card can't run, or two fields it could take. */
+    blocked?: Array<{
+        cardId: string;
+        title: string;
+        reason: 'blocked' | 'ambiguous';
+    }>;
+    /**
+     * In scope, on another dataset of the card's domain: the server decides
+     * when the card runs, through the domain's relationships, whether the
+     * filter applies. Never counted as reached.
+     */
+    relationshipPending?: Array<{
+        cardId: string;
+        title: string;
+        datasetName?: string;
+    }>;
+} | {
+    filterId: string;
+    label: string;
+    editable: false;
+    kind: 'global_date' | 'field' | 'other';
+    notEditable: {
+        reason: FilterNotEditableReason;
+        message: string;
+    };
+    reaches: string[];
+    excluded: string[];
+    blocked?: Array<{
+        cardId: string;
+        title: string;
+        reason: 'blocked' | 'ambiguous';
+    }>;
+    relationshipPending?: Array<{
+        cardId: string;
+        title: string;
+        datasetName?: string;
+    }>;
+};
+/** Server-side readers resolve relationship reach the way the card query does (RF-D15). */
+export type OutlineReachOptions = {
+    relationshipReach?: DashboardRelationshipReachResolver;
+};
+/**
+ * The calendar a summary reads defaults in: the report's, else a fixed one at
+ * the dashboard's own time, so a summary stays a pure function of its inputs.
+ * Only whether a default keeps its window is reported, never the dates it
+ * resolves to.
+ */
+export declare function outlineCalendar(calendar: CalendarContext | undefined, updatedAt: string | undefined): CalendarContext;
+export declare function summarizeFilter(dashboard: TDashboard, entry: FilterInputEntry, calendar?: CalendarContext, options?: OutlineReachOptions): OutlineFilter;
+/** Every filter on the dashboard, in the filter model's order. */
+export declare function outlineFilters(dashboard: TDashboard, calendar?: CalendarContext, options?: OutlineReachOptions): OutlineFilter[];
+/** One filter by its input id, or undefined. */
+export declare function outlineFilter(dashboard: TDashboard, filterId: string, calendar?: CalendarContext, options?: OutlineReachOptions): OutlineFilter | undefined;