react-semaphor 0.1.545 → 0.1.547

package/dist/surfboard/index.js

@@ -1,5 +1,5 @@
-import { a, R as s, D as o } from "../chunks/report-preferences-dialog-DUtuUL_5.js";
-import { C as f, E as D } from "../chunks/table-settings-CLZocegs.js";
+import { a, R as s, D as o } from "../chunks/report-preferences-dialog-DoVyriYC.js";
+import { C as f, E as D } from "../chunks/table-settings-WysCBj62.js";
 export {
   f as CONTROL_CARD_DEFAULT_VALUE,
   a as DisplayFormatPreferencesFields,

package/dist/types/components/index.d.ts

@@ -35,6 +35,8 @@ export { VisualEditingControls } from './editor/editor-main/visual-editing-contr
 export { AdvancedModeToggle } from './editor/editor-main/advanced-mode-toggle.js';
 export { AssistantProvider } from './assistant/assistant-provider.js';
 export { AssistantPanel, AssistantToolbarButton } from './assistant/assistant-entry-points.js';
+export { ArrangeLayoutButton } from './surfboard/arrange-layout-button.js';
+export { ScreenSizePreviewButton } from './surfboard/screen-size-preview-button.js';
 export type { AssistantPanelSurface } from './assistant/assistant-entry-points.js';
 export { useAssistant } from './assistant/use-assistant.js';
 export * from '../lib/types/common-types.js';

package/dist/types/components/surfboard/arrange-layout-button.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Arrange in the dashboard toolbar (responsive layouts RL-D13): lays the
+ * selected grid sheet out by kind on every screen size, or tidies it in its
+ * current order, with Undo on the toast (RL-INV-7). Shown while editing a
+ * grid sheet. Reads only the dashboard store, so semaphor-app mounts it in
+ * its own toolbar as well as the package's.
+ */
+export declare function ArrangeLayoutButton(): import("react").JSX.Element | null;

package/dist/types/components/surfboard/filter/types.d.ts

@@ -147,6 +147,13 @@ type BaseFilter = {
      * intersects with it (analytics kernel P2a-01).
      */
     dateOwner?: 'global_date';
+    /**
+     * Only for a mapping `relationship` target (relationship filter reach,
+     * RF-D10): the server resolves exactly these ids or blocks the card.
+     */
+    relationshipRoute?: {
+        relationshipIds: string[];
+    };
 };
 type FilterForString = BaseFilter & {
     operation: 'like' | 'not like';

package/dist/types/components/surfboard/screen-size-preview-button.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Opens and closes the sheet's screen-size bar (responsive layouts RL-D19,
+ * RL-D21). While editing, the bar shows Desktop, Laptop, Tablet, Phone and
+ * Small phone and lets Tablet and Phone be customized; while viewing, it is a
+ * look-only preview starting at the size the grid shows now. Closed by default.
+ * The host places it beside the Activity bell for people who can edit the
+ * dashboard. Reads only the dashboard store, so semaphor-app mounts it in its
+ * own toolbar too.
+ */
+export declare function ScreenSizePreviewButton(): import("react").JSX.Element | null;

package/dist/types/components/visual/matrix-table/matrix-card-view.d.ts

@@ -1,3 +1,4 @@
+import { SemaphorFilterReachEntry } from '../../../shared/analytics-protocol/index.js';
 import { MatrixCardCatalog } from '../../../lib/matrix-table/matrix-card-adapter.js';
 import { TCard, TFrame } from '../../../lib/types/common-types.js';
 import { MatrixDeliveryContext } from '../../../lib/matrix-table/matrix-delivery.js';
@@ -9,6 +10,8 @@ type Props = {
     capabilities?: MatrixInteractionHost['capabilities'];
     onSizingChange?: (sizes: Record<string, number>) => void;
     onDeliveryChange?: (context: MatrixDeliveryContext | undefined) => void;
+    /** The latest window's per-filter report, for the card's filter info (relationship filter reach RF-D13). */
+    onFilterReachChange?: (filterReach: SemaphorFilterReachEntry[]) => void;
     mode: 'dashboard' | 'expanded' | 'editor';
 };
 /** One renderer adapter for dashboard, editor and expanded hosts. */

package/dist/types/index.js

@@ -1,9 +1,9 @@
-import { C as s, E as r, V as l, i as o, c as i, g as n, f as d, b as m, e as u, d as E, a as c, u as p, s as C, h as T, j as D, q as A, o as I, m as _, n as F, p as S, k as b, l as L, r as f, t as N } from "../chunks/table-settings-CLZocegs.js";
-import { C as y, D as M, L as g, P as h, e as x, g as O, j as V, h as k, k as w, d as U, b as B, i as K, c as z, n as v, f as P } from "../chunks/validators-DMHTpf7a.js";
-import { D as q } from "../chunks/token-types-DBbZVQsm.js";
-import { B as Q, a as j, p as W, r as J } from "../chunks/bookmark-state-CXw7lZ50.js";
-import { r as H, a as Z } from "../chunks/pivot-result-identity-DJhXXcns.js";
-import { D as ee } from "../chunks/report-runtime-context-Dq8XyODK.js";
+import { C as s, E as r, V as l, i as o, c as i, g as n, f as d, b as m, e as u, d as E, a as c, u as p, s as C, h as T, j as D, q as A, o as I, m as _, n as F, p as S, k as b, l as L, r as f, t as N } from "../chunks/table-settings-WysCBj62.js";
+import { C as y, D as M, L as g, P as h, e as x, g as O, j as V, h as k, k as w, d as U, b as B, i as K, c as z, n as v, f as P } from "../chunks/validators-C-aOQlTB.js";
+import { D as q } from "../chunks/token-types-BMqRmT-C.js";
+import { B as Q, a as j, p as W, r as J } from "../chunks/bookmark-state-Cu-a5ie_.js";
+import { r as H, a as Z } from "../chunks/pivot-result-identity-C-Q1j1Wb.js";
+import { D as ee } from "../chunks/report-runtime-context-hWiTCzFV.js";
 const e = [
   "concatenate",
   "conditional-category",

package/dist/types/lib/charts/table-chart-types.d.ts

@@ -0,0 +1,4 @@
+import { TChartType } from './types.js';
+/** The chart types that render as tables. No runtime imports: server-safe code reads these. */
+export declare const TABLE_CHART_TYPES: readonly ["table", "pivotTable", "aggregateTable", "matrixTable", "detailTable"];
+export declare function isTableChartType(chartType: TChartType | string | undefined | null): boolean;

package/dist/types/lib/charts/types.d.ts

@@ -7,6 +7,7 @@ import { SemaphorResultColumn } from '../../shared/analytics-protocol/index.js';
 import { PresentationExecutionSnapshot } from '../../shared/format-utils/index.js';
 import { CartesianTemporalPresentation } from '../formatters/cartesian-temporal-presentation.js';
 import { CartesianFieldRoles } from './cartesian-fields.js';
+import { TABLE_CHART_TYPES, isTableChartType } from './table-chart-types.js';
 export type ChartConfigParams = {
     card: TCard;
     data: any[];
@@ -49,8 +50,7 @@ export type BlurEffectProps = {
     blurColor?: string;
 };
 export type TChartType = 'bar' | 'horizontalBar' | 'line' | 'area' | 'stackedArea' | 'combo' | 'pie' | 'doughnut' | 'radar' | 'polarArea' | 'bubble' | 'scatter' | 'stackedBar' | 'stackedLine' | 'table' | 'pivotTable' | 'aggregateTable' | 'matrixTable' | 'detailTable' | 'kpi' | 'pyramid' | 'tornado' | 'range' | 'text' | 'map' | 'funnel' | 'bullet' | 'heatmap' | 'treemap' | 'custom';
-export declare const TABLE_CHART_TYPES: readonly ["table", "pivotTable", "aggregateTable", "matrixTable", "detailTable"];
-export declare function isTableChartType(chartType: TChartType | string | undefined | null): boolean;
+export { TABLE_CHART_TYPES, isTableChartType };
 export declare function isChartJsVisualType(chartType: TChartType | string | undefined | null): boolean;
 export declare const REGULAR_TABLE_SETTINGS_CHART_TYPES: readonly ["table", "matrixTable", "pivotTable", "aggregateTable", "detailTable"];
 export declare function supportsRegularTableSettings(chartType: TChartType | string | undefined | null): boolean;

package/dist/types/lib/dashboard-inputs/dashboard-filter-mapping-authoring.d.ts

@@ -1,6 +1,7 @@
 import { TFilter } from '../../components/surfboard/filter/types.js';
 import { DashboardInputScope, TCard, TDashboard } from '../types/common-types.js';
-import { DashboardFilterApplication, DashboardFilterCardApplication, DashboardFilterTarget, DashboardFilterTargetField } from '../../shared/dashboard-authoring/index.js';
+import { DashboardFilterApplication, DashboardFilterCardApplication, DashboardFilterRelationshipTarget, DashboardFilterFieldTarget, DashboardFilterTarget, DashboardFilterTargetField, DashboardFilterOptionSource, FilterReachPreviewCard, FilterReachCardPreview, FilterReachPathOption } from '../../shared/dashboard-authoring/index.js';
+import { SemaphorRelationshipRoute, SemaphorSkippedConstraintReason } from '../../shared/analytics-protocol/index.js';
 import { FilterRef, ReachedCard } from '../../shared/dashboard-authoring/filter-model/index.js';
 /**
  * Filter mapping (one filter model M3, SPEC 4.4): the Cards tab of any filter
@@ -9,19 +10,169 @@ import { FilterRef, ReachedCard } from '../../shared/dashboard-authoring/filter-
  */
 export type DashboardFilterMappingCandidateCatalog = {
     status: 'ready';
-    targets: DashboardFilterTarget[];
+    targets: DashboardFilterFieldTarget[];
 } | {
     status: 'metadataUnavailable';
     message?: string;
 };
-export type DashboardFilterMappingDraftDecision = {
-    kind: 'bound';
-    target: DashboardFilterTarget;
+/**
+ * What the author decided for a card, as the draft stands: what Accept saves
+ * (relationship filter reach S-D, RF-INV-14). A change staged in this
+ * popover, else the card's saved entry, else Auto.
+ */
+export type DashboardFilterCardDecision = 
+/** No entry of its own: the card applies the filter on its own field when that is proven, else through the domain's relationships. */
+{
+    kind: 'auto';
+} | {
+    kind: 'field';
+    target: DashboardFilterFieldTarget;
+}
+/** A chosen relationship path (RF-D10). */
+ | {
+    kind: 'path';
+    target: DashboardFilterRelationshipTarget;
+} | {
+    kind: 'excluded';
+};
+/** Where a row's decision comes from: a change in this popover, the saved mapping, or neither. */
+export type DashboardFilterDecisionOrigin = 'staged' | 'saved' | 'none';
+/** What runs for a card's decision, as the draft stands (RF-INV-14). */
+export type DashboardFilterCardOutcome = 
+/** On a field of the card: the one the author bound, the one Auto proves (or a click borrows), or the one a SQL card takes the value by. */
+{
+    kind: 'appliesOnField';
+    target: DashboardFilterFieldTarget;
+    how: 'bound';
+} | {
+    kind: 'appliesOnField';
+    target: DashboardFilterFieldTarget;
+    how: 'automatic';
+} | {
+    kind: 'appliesOnField';
+    target: DashboardFilterFieldTarget;
+    how: 'sql';
+    name: string;
+}
+/** Through the domain's relationships, on the server's route. */
+ | {
+    kind: 'appliesThroughPath';
+    route: SemaphorRelationshipRoute;
+}
+/** The card's query already uses the value's dataset, so no path is needed (ledger R-05). */
+ | {
+    kind: 'appliesOnOwnData';
+}
+/** Auto, and more than one equally preferred path: the card skips the filter until one is chosen; Accept isn't refused (RF-D28). */
+ | {
+    kind: 'needsPath';
+}
+/**
+ * Auto, and the card's fields need the author: a same-named field to
+ * accept, a SQL card that takes the value by name until a field is
+ * chosen, or a choice among fields, which refuses Accept.
+ */
+ | {
+    kind: 'needsField';
+    need: 'accept';
+    suggestion: DashboardFilterFieldTarget;
+    reason?: SemaphorSkippedConstraintReason;
+} | {
+    kind: 'needsField';
+    need: 'sqlByName';
+    name?: string;
+    reason?: SemaphorSkippedConstraintReason;
+} | {
+    kind: 'needsField';
+    need: 'choose';
+    reason?: SemaphorSkippedConstraintReason;
+}
+/**
+ * The filter doesn't reach the card, with the server's reason or the
+ * card's guidance when there is one. `unmatched`: a field a click carries
+ * matches none of the card's fields, so the click drops it (no choice).
+ */
+ | {
+    kind: 'notApplied';
+    reason?: SemaphorSkippedConstraintReason;
+    message?: string;
+    unmatched?: true;
+}
+/**
+ * The decision can't run: a stale field, a path the domain no longer has,
+ * a path for another value field. Refuses Accept. `target`: the field that
+ * can't run when the decision doesn't name it (a click's borrowed binding).
+ */
+ | {
+    kind: 'blocked';
+    message: string;
+    reason?: SemaphorSkippedConstraintReason;
+    target?: DashboardFilterFieldTarget;
 } | {
     kind: 'excluded';
+}
+/** Waiting for the server's answer for this decision, or the request failed (ledger R-08). */
+ | {
+    kind: 'checking';
+    failed?: true;
+}
+/** The card's source isn't chosen yet, or its fields couldn't be loaded, which refuses Accept. */
+ | {
+    kind: 'unavailable';
+    cause: 'source' | 'fields';
+    message?: string;
+    reason?: SemaphorSkippedConstraintReason;
+};
+type OutcomeOf<K extends DashboardFilterCardOutcome['kind']> = Extract<DashboardFilterCardOutcome, {
+    kind: K;
+}>;
+/**
+ * A card's decision with what can run for it: exactly the pairs `cardRow`
+ * makes (RF-INV-14). A row changed after `cardRow` into another pair, such
+ * as Automatic with a bound field, doesn't compile (ledger R-27).
+ */
+export type DashboardFilterCardState = {
+    decision: Extract<DashboardFilterCardDecision, {
+        kind: 'auto';
+    }>;
+    outcome: Extract<DashboardFilterCardOutcome, {
+        kind: 'appliesOnField';
+        how: 'automatic' | 'sql';
+    }> | OutcomeOf<'appliesThroughPath' | 'appliesOnOwnData' | 'needsPath' | 'needsField' | 'notApplied' | 'blocked' | 'checking' | 'unavailable'>;
+} | {
+    decision: Extract<DashboardFilterCardDecision, {
+        kind: 'field';
+    }>;
+    outcome: Extract<DashboardFilterCardOutcome, {
+        kind: 'appliesOnField';
+        how: 'bound';
+    }> | OutcomeOf<'blocked' | 'notApplied' | 'unavailable'>;
+} | {
+    decision: Extract<DashboardFilterCardDecision, {
+        kind: 'path';
+    }>;
+    outcome: OutcomeOf<'appliesThroughPath' | 'appliesOnOwnData' | 'checking' | 'blocked' | 'notApplied'>;
+} | {
+    decision: Extract<DashboardFilterCardDecision, {
+        kind: 'excluded';
+    }>;
+    outcome: OutcomeOf<'excluded' | 'unavailable' | 'notApplied'>;
 };
-export type DashboardFilterMappingDraftStatus = 'pendingSource' | 'automatic' | 'suggested' | 'needsMapping' | 'mapped' | 'notApplicable' | 'excluded' | 'invalidMapping' | 'metadataUnavailable';
-export type DashboardFilterMappingDraftRow = {
+/** What a row shows, in the names the Cards tab has always used; read from `presentDashboardFilterMappingRow`. */
+export type DashboardFilterMappingRowState = 'pendingSource' | 'automatic' | 'suggested' | 'needsMapping' | 'mapped' | 'notApplicable' | 'excluded' | 'invalidMapping' | 'metadataUnavailable'
+/** Auto, through the domain's relationships (with a route), or on the card's own data (none). */
+ | 'relationship'
+/** Auto, and more than one equally preferred path (P-7, RF-D10). */
+ | 'chooseRoute'
+/** Waiting for the server's relationship answer, or it failed. */
+ | 'relationshipChecking';
+/**
+ * One card in the Cards tab: the author's decision and what runs for it
+ * (`DashboardFilterCardState`), made only by `cardRow`. Every reader (the
+ * panel, the summary, Accept, the click review) reads these two, through
+ * `presentDashboardFilterMappingRow` for display.
+ */
+export type DashboardFilterMappingDraftRow = DashboardFilterCardState & {
     cardId: string;
     /** The panel reads the title and meta line from it. */
     card: TCard;
@@ -31,13 +182,135 @@ export type DashboardFilterMappingDraftRow = {
     /** The section's title, for a card in a Document section. */
     sectionTitle?: string;
     executionKind: 'config' | 'sql' | 'unconfigured';
-    status: DashboardFilterMappingDraftStatus;
-    candidates: DashboardFilterTarget[];
-    selectedTarget?: DashboardFilterTarget;
+    decisionOrigin: DashboardFilterDecisionOrigin;
+    /** The card's fields that can take the filter. */
+    fields: DashboardFilterFieldTarget[];
+    /** The card's equally preferred paths when it has a tie, whatever the decision (RF-D27). */
+    paths: FilterReachPathOption[];
+    /** The card's saved entry, as saved. */
     persistedApplication?: DashboardFilterCardApplication;
-    metadataMessage?: string;
-    guidanceMessage?: string;
-    automaticFieldName?: string;
+};
+/** The row's control, as it reads when closed. */
+export type DashboardFilterMappingRowTrigger = {
+    kind: 'notApplied';
+}
+/** A field, with "Auto ·" or "Suggested ·" before it. */
+ | {
+    kind: 'field';
+    target: DashboardFilterFieldTarget;
+    prefix?: 'Auto' | 'Suggested';
+}
+/** A SQL card's Auto: the field it takes the value by. */
+ | {
+    kind: 'sqlAuto';
+    target: DashboardFilterFieldTarget;
+    name: string;
+}
+/** A path in words, with "Auto ·" before it when the domain's relationships chose it. */
+ | {
+    kind: 'route';
+    route: SemaphorRelationshipRoute;
+    auto: boolean;
+} | {
+    kind: 'checking';
+} | {
+    kind: 'text';
+    text: string;
+    tone: 'muted' | 'strong' | 'attention';
+};
+/**
+ * What Automatic does on the card, said under its menu entry: the path or
+ * field it uses, that it skips the card until a path is chosen, or that it
+ * doesn't reach the card. Absent when not known for the row's decision.
+ */
+export type DashboardFilterAutoDescription = {
+    kind: 'skipsUntilPathChosen';
+} | {
+    kind: 'route';
+    route: SemaphorRelationshipRoute;
+} | {
+    kind: 'ownData';
+} | {
+    kind: 'field';
+    target: DashboardFilterFieldTarget;
+} | {
+    kind: 'checking';
+} | {
+    kind: 'notApplied';
+    reason?: SemaphorSkippedConstraintReason;
+};
+/** A line under the row. */
+export type DashboardFilterMappingRowNote = 
+/** A chosen path that can't run: the server's reason, else its message. */
+{
+    kind: 'pathBlocked';
+    message: string;
+    reason?: SemaphorSkippedConstraintReason;
+} | {
+    kind: 'fieldBlocked';
+} | {
+    kind: 'needsPath';
+} | {
+    kind: 'fieldsUnavailable';
+    message: string;
+} | {
+    kind: 'sqlPinnedSources';
+};
+/**
+ * What a row shows, counts as and offers: one reading of its decision and
+ * outcome (RF-INV-14). The panel, the popover summary and the click review
+ * read rows only through it.
+ */
+export type DashboardFilterMappingRowView = {
+    state: DashboardFilterMappingRowState;
+    /** The status column of the table review. */
+    label: string;
+    tone: 'quiet' | 'review' | 'warning' | 'invalid';
+    /** How the row counts in the summary; none while its source or the server's answer is pending. */
+    count?: 'covered' | 'review' | 'excluded' | 'invalid';
+    /** Counted to review or invalid. */
+    attention: boolean;
+    /** Accept is refused while the row stands: a decision that can't run, a field to choose, fields not loaded. */
+    blocksAccept: boolean;
+    /** A menu, or a control that only says why there is nothing to choose. */
+    control: {
+        kind: 'menu';
+    } | {
+        kind: 'static';
+        text: string;
+        offerFieldsRetry: boolean;
+    };
+    trigger: DashboardFilterMappingRowTrigger;
+    border: 'default' | 'review' | 'invalid' | 'dashed';
+    note?: DashboardFilterMappingRowNote;
+    /**
+     * The menu, in order: Auto, the tie's paths, the card's fields, "Don't
+     * apply", and "Check relationships again" while a check failed. The
+     * decision is the one checked entry; picking it again changes nothing.
+     */
+    menu: {
+        auto: {
+            label: string;
+            checked: boolean;
+            description?: DashboardFilterAutoDescription;
+        };
+        paths: Array<{
+            path: FilterReachPathOption;
+            checked: boolean;
+        }>;
+        /** The field a `field` decision binds, as the card lists it. */
+        checkedField?: DashboardFilterFieldTarget;
+        /**
+         * The field Auto proves on this card: picking it keeps Auto, so a filter
+         * with no mapping isn't mapped by confirming what already applies.
+         */
+        autoField?: DashboardFilterFieldTarget;
+        excludedChecked: boolean;
+        /** "Check relationships again" (ledger R-08). */
+        offerRetry: boolean;
+    };
+    /** The row involves the domain's relationships, so "Manage relationships" helps. */
+    throughRelationships: boolean;
 };
 export type DashboardFilterMappingGroup = {
     sheetId: string;
@@ -99,6 +372,11 @@ export type DashboardFilterMappingRequest = {
     stagedDefinition?: TFilter;
     /** The scope being edited, if changed; otherwise the saved scope, unnarrowed (OF-D8). */
     stagedScope?: DashboardInputScope;
+    /**
+     * The Option Source being edited: undefined keeps the saved one, null drops
+     * it. The filter's value is judged by it, as the runtime will (ledger R-04).
+     */
+    stagedOptionSource?: DashboardFilterOptionSource | null;
     candidatesByCardId: Record<string, DashboardFilterMappingCandidateCatalog | undefined>;
     /** Grounded field that supplies the current filter value. */
     selectionField?: Pick<DashboardFilterTargetField, 'name' | 'sourceField'> & Partial<Pick<DashboardFilterTargetField, 'source'>>;
@@ -111,22 +389,32 @@ export type DashboardFilterMappingRequest = {
     selectionDataType?: string;
     /** Re-check saved targets after the option value field changed. */
     revalidatePersistedTargets?: boolean;
-    decisionsByCardId?: Record<string, DashboardFilterMappingDraftDecision | undefined>;
+    decisionsByCardId?: Record<string, DashboardFilterCardDecision | undefined>;
+    /**
+     * The server's relationship preview per card (`POST /api/v1/filter-reach`,
+     * relationship filter reach Phase 3). The draft never resolves routes.
+     */
+    relationshipPreviewsByCardId?: Record<string, FilterReachCardPreview | undefined>;
+    /**
+     * The server preview could not be read. Cards waiting on it say so instead
+     * of checking forever; nothing is saved for them, so Accept is not blocked
+     * (ledger R-08).
+     */
+    relationshipPreviewFailed?: boolean;
     /** Test seam for new binding ids; production uses opaque random UUIDs. */
     createId?: () => string;
 };
 /**
- * One presentation-neutral projection of authoritative Cards-tab rows.
- * Consumers must not independently reinterpret draft statuses when deciding
- * whether an author needs to act.
+ * The Cards tab's counts, from each row's view: the one reading every
+ * surface uses to decide whether the author needs to act.
  */
 export declare function summarizeDashboardFilterMappingRows(rows: DashboardFilterMappingDraftRow[]): DashboardFilterMappingStatusSummary;
 /**
  * One Cards row for a source-qualified value field that is not a toolbar
  * filter, such as a field a click carries. It is the same decision chain the
- * toolbar filter's rows go through (`rowFromCandidates`), so automatic,
- * suggested, mapped, excluded and needs-mapping mean the same thing on every
- * authoring surface. Equality is the only operation a click applies.
+ * toolbar filter's rows go through (`cardRow`), so automatic, suggested,
+ * mapped, excluded and needs-mapping mean the same thing on every authoring
+ * surface. Equality is the only operation a click applies.
  */
 export declare function buildDashboardFilterMappingDraftRowForValueField(params: {
     card: TCard;
@@ -136,10 +424,47 @@ export declare function buildDashboardFilterMappingDraftRowForValueField(params:
     sectionTitle?: string;
     valueField: DashboardFilterTargetField;
     catalog: DashboardFilterMappingCandidateCatalog | undefined;
-    decision?: DashboardFilterMappingDraftDecision;
+    /** The click's own decision for the card: its binding, "Don't apply", or none (Auto). */
+    decision?: DashboardFilterCardDecision;
     persistedApplication?: DashboardFilterCardApplication;
     /** Bindings already accepted elsewhere for this value field, offered as inherited matches. */
     acceptedTargets?: DashboardFilterTarget[];
+    /** A filter's binding Auto applies first (`cardRow`'s `borrowedTarget`). */
+    borrowedTarget?: DashboardFilterFieldTarget;
+    /** What a card with no matching field gets (`cardRow`'s `unmatchedField`). */
+    unmatchedField?: 'choose' | 'notApplied';
 }): DashboardFilterMappingDraftRow;
+/** The decision that saves a target the author picked: a field, or a path. */
+export declare function dashboardFilterCardDecisionForTarget(target: DashboardFilterTarget): DashboardFilterCardDecision;
+/**
+ * A card's decision as the draft stands, and where it comes from: a change
+ * staged in this popover, else the saved entry, else Auto. The rows and the
+ * preview's card list both read it here.
+ */
+export declare function draftCardDecision(staged: DashboardFilterCardDecision | undefined, persisted: DashboardFilterCardApplication | undefined): {
+    decision: DashboardFilterCardDecision;
+    origin: DashboardFilterDecisionOrigin;
+};
+/**
+ * What a row shows, counts as and offers, read from its decision and
+ * outcome only (relationship filter reach S-D, RF-INV-14).
+ */
+export declare function presentDashboardFilterMappingRow(row: DashboardFilterMappingDraftRow): DashboardFilterMappingRowView;
 /** The one entry point of M3 (SPEC 4.4). Pure. */
 export declare function draftDashboardFilterMapping(request: DashboardFilterMappingRequest): DashboardFilterMappingDraftResult;
+/**
+ * The cards in a staged filter's scope whose relationship reach the server
+ * preview should resolve, each with the route the draft runs it with (ledger
+ * R-02): cards with a chosen route, staged or saved, and cards the card
+ * target decision runs through the domain's relationships when unmapped (row
+ * 7r). Empty when there are none, so no preview is requested.
+ */
+export declare function listRelationshipPreviewCards(params: {
+    ref: FilterRef;
+    dashboard: TDashboard;
+    stagedDefinition?: TFilter;
+    stagedScope?: DashboardInputScope;
+    stagedOptionSource?: DashboardFilterOptionSource | null;
+    decisionsByCardId?: Record<string, DashboardFilterCardDecision | undefined>;
+}): FilterReachPreviewCard[];
+export {};

package/dist/types/lib/dashboard-inputs/dashboard-filter-value-identity.d.ts

@@ -0,0 +1,65 @@
+import { TFilter, TFilterValue } from '../../components/surfboard/filter/types.js';
+import { NormalizedFilterDashboardInput } from '../types/common-types.js';
+import { DashboardFilterLogicalValueField, DashboardFilterOptionSource, DashboardFilterRelationshipTarget, DashboardFilterTargetField, DashboardFilterTargetSource } from '../../shared/dashboard-authoring/index.js';
+import { SemaphorConnectionCapabilities } from '../../shared/analytics-protocol/index.js';
+export type DashboardFilterSourceResolutionContext = {
+    connectionType?: string;
+    capabilities?: Pick<SemaphorConnectionCapabilities, 'dialect' | 'prefixLevels'>;
+};
+/**
+ * Resolves the concrete source carried by an Option Source field, falling
+ * back to the Option Source declaration for older field refs that omit it.
+ */
+export declare function resolveDashboardFilterOptionFieldSource(field: DashboardFilterOptionSource['valueField'], fallbackSource: DashboardFilterOptionSource['source']): DashboardFilterTargetSource;
+export declare function resolveDashboardFilterBackingSourceResolution(filter: TFilter, context?: DashboardFilterSourceResolutionContext): import('../../shared/analytics-protocol/index.js').SemaphorSourceEntityResolution<Record<string, unknown>>;
+/** Resolves the one source that owns an ordinary dashboard filter field. */
+export declare function resolveDashboardFilterBackingSource(filter: TFilter, context?: DashboardFilterSourceResolutionContext): DashboardFilterTargetSource | undefined;
+/**
+ * Metadata authoring may inspect a complete persisted qualified source even
+ * when stale selected-entity inventory no longer contains it. Runtime source
+ * resolution remains fail-closed through resolveDashboardFilterBackingSource.
+ */
+export declare function resolveDashboardFilterMappingCandidateSource(filter: TFilter, context?: DashboardFilterSourceResolutionContext): DashboardFilterTargetSource | undefined;
+/**
+ * Resolves every proven identity by which the selected filter field may map.
+ * A physical dataset selected within a semantic domain legitimately has both
+ * a physical backing identity and a semantic projection; the consuming card
+ * chooses the identity present in its own executable-source inventory.
+ */
+export declare function resolveDashboardFilterMappingSources(filter: TFilter): DashboardFilterTargetSource[];
+/**
+ * Authoring counterpart to resolveDashboardFilterMappingSources. It may carry
+ * a complete qualified backing candidate when persisted entity inventory is
+ * stale, while the semantic projection still requires a resolved entity.
+ */
+export declare function resolveDashboardFilterMappingCandidateSources(filter: TFilter, context?: DashboardFilterSourceResolutionContext): DashboardFilterTargetSource[];
+/** Resolves the ordinary filter field used as the pre-Option-Source value key. */
+export declare function deriveDashboardFilterLogicalSelectionField(filter: TFilter): Pick<DashboardFilterTargetField, 'name'> | undefined;
+/** The filter's logical value field: its Option Source's value field, else its own field. */
+export declare function filterInputLogicalValueField(input: NormalizedFilterDashboardInput, filterValue?: TFilterValue): DashboardFilterLogicalValueField | undefined;
+/** The sources a filter's values belong to: its Option Source's, else its own field's. */
+export declare function filterInputValueSources(input: NormalizedFilterDashboardInput): DashboardFilterTargetSource[];
+/**
+ * The source-qualified fields whose values a toolbar filter holds. A filter
+ * with an option source has exactly one; an ordinary filter has one per
+ * source it is proven to address.
+ */
+export declare function dashboardFilterInputValueFields(input: NormalizedFilterDashboardInput): DashboardFilterTargetField[];
+/**
+ * Whether an author-chosen relationship route (RF-D10) still ends at the
+ * filter's value field: the field the filter's values belong to (its Option
+ * Source's value field when it has one). A route chosen for another field,
+ * as after the Option Source moves to another dataset, can't run and is stale
+ * until chosen again. The card target decision, the Cards tab draft and save
+ * validation all ask here (relationship filter reach ledger R-12).
+ */
+export declare function relationshipTargetFollowsValueField(input: NormalizedFilterDashboardInput, target: DashboardFilterRelationshipTarget): boolean;
+/**
+ * The target that saves an author's choice of a relationship route (RF-D10):
+ * the route's ids and the filter's value field as its semantic dataset in the
+ * card's domain, the field `relationshipTargetFollowsValueField` checks. A
+ * value field can also have a physical identity (a physical dataset in a
+ * semantic domain); the route ends at the semantic one. The server preview
+ * builds the Cards tab's choices here (ledger R-16).
+ */
+export declare function relationshipRouteTarget(input: NormalizedFilterDashboardInput, domainId: string, relationshipIds: readonly string[]): DashboardFilterRelationshipTarget | undefined;

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

@@ -80,3 +80,9 @@ export declare function removeDashboardInputSlotsById(values: DashboardInputValu
  * are the stored slots, read without building the model.
  */
 export declare function savedDefaultInputValues(dashboard: Pick<TDashboard, 'defaultInputValues' | 'defaultFilterValues'>): DashboardInputValues | undefined;
+/**
+ * Every value an input holds, saved or live, removed: its shared slot and its
+ * slot on every sheet, card and Document section. Shared by the store's
+ * input removal and the dashboard reducer's `filter.remove`.
+ */
+export declare function removeDashboardInputFromValues(values: DashboardInputValues | undefined, inputId: string): DashboardInputValues;

package/dist/types/lib/dashboard-inputs/filter-settings.d.ts

@@ -108,6 +108,8 @@ export declare function buildFilterInputFromField(params: {
     scope: DashboardInputScope;
     existingInputs: readonly DashboardInput[];
     createId?: () => string;
+    /** The filter's label (and variable name); default the field's label. */
+    label?: string;
 }): EmbeddedFilterDashboardInput;
 /**
  * A new filter input holding this definition (one filter model Phase 5):

package/dist/types/lib/dashboard-inputs/prepare-loaded-dashboard.d.ts

@@ -0,0 +1,15 @@
+import { TDashboard } from '../types/common-types.js';
+/**
+ * A saved dashboard as it enters a runtime (one filter model SPEC 5.1): the
+ * filter model's stored shape, every filter an embedded input, when the
+ * model reads it without issues; otherwise the template as received, read
+ * tolerantly (rejected inputs left out) and refused on save. Then the
+ * Include / Exclude repair. Loading never throws on model issues.
+ *
+ * The one entry for every runtime: the client load (`useDashboard`), the
+ * store's replace and load (`setDashboard`, `setDashboardWithFilterValues`)
+ * and the server's saved-dashboard reader, so they all hold the same shape.
+ * The same object when nothing changes. Alias-based text is bound to stable
+ * input ids before the upgrade (`upgradeToStoredDashboard`, ledger P5-11).
+ */
+export declare function prepareLoadedDashboard<TDashboardShape extends TDashboard>(dashboard: TDashboardShape): TDashboardShape;