react-semaphor 0.1.546 → 0.1.548

package/dist/data-app-sdk-validation/index.js

@@ -3,7 +3,7 @@ import { Z as Q } from "../chunks/matrix-operation-contract-D6vYkZK4.js";
 import "../chunks/analytics-base-schemas-BKs3flFS.js";
 import "zod";
 import { p as W } from "../chunks/report-runtime-context-hWiTCzFV.js";
-import { o as U } from "../chunks/source-entity-resolution-BIGRvtbG.js";
+import { o as U } from "../chunks/source-entity-resolution-D195CrYS.js";
 import { toSemaphorMetricIntent as J, toSemaphorAnalysisIntent as V, toSemaphorRecordsIntent as G, toSemaphorSqlIntent as L, toSemaphorMatrixIntent as Z, toSemaphorInputOptionsIntent as X } from "../data-app-sdk-adapters/index.js";
 import { m as Y } from "../chunks/matrix-card-LiMEipvq.js";
 function ee({

package/dist/index.js

@@ -1,10 +1,10 @@
-import { D as M } from "./chunks/dashboard-C3CoKbGY.js";
-import { C as fa, E as ma } from "./chunks/table-settings-CunhoDUi.js";
-import { C as U, b as V, c as z, d as H, e as W, f as q } from "./chunks/report-preferences-dialog-4QEZWe5U.js";
-import { g as ga, A as Ca, h as ba, a as ya, R as va, D as Da } from "./chunks/report-preferences-dialog-4QEZWe5U.js";
+import { D as M } from "./chunks/dashboard-BZHL9a-z.js";
+import { C as fa, E as ma } from "./chunks/table-settings-WysCBj62.js";
+import { C as U, b as V, c as z, d as H, e as W, f as q } from "./chunks/report-preferences-dialog-CM7kXmXp.js";
+import { g as ga, A as Ca, h as ba, a as ya, R as va, D as Da } from "./chunks/report-preferences-dialog-CM7kXmXp.js";
 import { jsx as o, jsxs as b } from "react/jsx-runtime";
-import { E as P, F as $, S as G, a as K, U as Q, c as J, A as Y, C as X, u as L, d as Z, f as ee, g as ae, V as te, e as _, h as N, s as se, R as re } from "./chunks/semaphor-ready-indicator-4zpRHE-X.js";
-import { O as Aa, aw as Sa, ax as Ta, ay as wa, B as xa, a5 as Ba, I as Fa, G as Pa, z as _a, aG as Na, M as Ra, W as La, k as Ia, n as ja, n as ka, o as Oa, H as Ma, ar as Ua, at as Va, au as za, as as Ha, ai as Wa, al as qa, aF as $a, a9 as Ga, aq as Ka, a2 as Qa, aA as Ja, aB as Ya, ad as Xa, am as Za, y as et, x as at, v as tt, w as st, aJ as rt, a8 as ot, an as nt, ao as it, ah as lt, ak as ct, aE as ut, aD as dt, aC as pt, aI as ft, aH as mt, aj as ht, a7 as gt, a6 as Ct, T as bt, ab as yt, ap as vt, af as Dt, ac as Et, ae as At, ag as St, X as Tt, Y as wt, Z as xt, aa as Bt, P as Ft, N as Pt, t as _t, az as Nt, r as Rt, K as Lt, _ as It, a0 as jt, $ as kt, a1 as Ot, q as Mt, j as Ut, J as Vt, L as zt, l as Ht, a4 as Wt, Q as qt, a3 as $t, i as Gt, p as Kt, m as Qt, av as Jt } from "./chunks/semaphor-ready-indicator-4zpRHE-X.js";
+import { E as P, F as $, S as G, a as K, U as Q, c as J, A as Y, C as X, u as L, d as Z, f as ee, g as ae, V as te, e as _, h as N, s as se, R as re } from "./chunks/semaphor-ready-indicator-Ol6VcaR7.js";
+import { O as Aa, aw as Sa, ax as Ta, ay as wa, B as xa, a5 as Ba, I as Fa, G as Pa, z as _a, aG as Na, M as Ra, W as La, k as Ia, n as ja, n as ka, o as Oa, H as Ma, ar as Ua, at as Va, au as za, as as Ha, ai as Wa, al as qa, aF as $a, a9 as Ga, aq as Ka, a2 as Qa, aA as Ja, aB as Ya, ad as Xa, am as Za, y as et, x as at, v as tt, w as st, aJ as rt, a8 as ot, an as nt, ao as it, ah as lt, ak as ct, aE as ut, aD as dt, aC as pt, aI as ft, aH as mt, aj as ht, a7 as gt, a6 as Ct, T as bt, ab as yt, ap as vt, af as Dt, ac as Et, ae as At, ag as St, X as Tt, Y as wt, Z as xt, aa as Bt, P as Ft, N as Pt, t as _t, az as Nt, r as Rt, K as Lt, _ as It, a0 as jt, $ as kt, a1 as Ot, q as Mt, j as Ut, J as Vt, L as zt, l as Ht, a4 as Wt, Q as qt, a3 as $t, i as Gt, p as Kt, m as Qt, av as Jt } from "./chunks/semaphor-ready-indicator-Ol6VcaR7.js";
 import * as T from "react";
 import I, { useMemo as R, useEffect as j } from "react";
 import { C as Xt, D as Zt, L as es, P as as, e as ts, g as ss, j as rs, h as os, k as ns, d as is, b as ls, i as cs, c as us, n as ds, f as ps } from "./chunks/validators-C-aOQlTB.js";
@@ -15,26 +15,26 @@ import "./chunks/matrix-operation-contract-D6vYkZK4.js";
 import "./chunks/analytics-base-schemas-BKs3flFS.js";
 import "./value-format-preferences/index.js";
 import { D as ms } from "./chunks/token-types-BMqRmT-C.js";
-import { c as gs, A as Cs, b as bs, g as ys, D as vs, e as Ds, f as Es, d as As, S as Ss, U as Ts, a as ws, V as xs, W as Bs, i as Fs, u as Ps } from "./chunks/dashboard-briefing-launcher-Be4h-7My.js";
+import { c as gs, A as Cs, b as bs, g as ys, D as vs, e as Ds, f as Es, d as As, S as Ss, U as Ts, a as ws, V as xs, W as Bs, i as Fs, u as Ps } from "./chunks/dashboard-briefing-launcher-DML-cAzB.js";
 import { n as Ns, s as Rs, u as Ls } from "./chunks/normalize-dashboard-for-dirty-check-XKgH3GFX.js";
 import { createRoot as ne } from "react-dom/client";
-import "./chunks/shelf-drop-preview-context-Cfw7TRAx.js";
+import "./chunks/shelf-drop-preview-context-C2SEC3I9.js";
 import "./chunks/index-CuHybtft.js";
 import { D as js } from "./chunks/report-runtime-context-hWiTCzFV.js";
 import { c as B } from "./chunks/_commonjsHelpers-DimLPMtv.js";
 import { P as ie, a as le, B as ce, b as ue, c as de } from "./chunks/switch-CEBOR4n7.js";
-import "./chunks/global-date-filter-utils-9d6m9-FE.js";
+import "./chunks/global-date-filter-utils-CeeFJ1CP.js";
 import { r as Os, a as Ms } from "./chunks/pivot-result-identity-C-Q1j1Wb.js";
-import { a as pe } from "./chunks/resolve-dashboard-input-context-UpK_LBpL.js";
-import { k as Vs, f as zs, n as Hs, m as Ws, s as qs, t as $s, j as Gs, h as Ks, o as Qs, g as Js, d as Ys, i as Xs, u as Zs, q as er } from "./chunks/resolve-dashboard-input-context-UpK_LBpL.js";
+import { a as pe } from "./chunks/resolve-dashboard-input-context-BmWF9hSl.js";
+import { k as Vs, f as zs, n as Hs, m as Ws, s as qs, t as $s, j as Gs, h as Ks, o as Qs, g as Js, d as Ys, i as Xs, u as Zs, q as er } from "./chunks/resolve-dashboard-input-context-BmWF9hSl.js";
 import "./chunks/index-CtoK1Lgu.js";
 import "react-dom";
-import "./chunks/index-DkQkMKa1.js";
+import "./chunks/index-DeDHr3iz.js";
 import "./chunks/appearance-context-DEYtWinQ.js";
 import "./chunks/color-CJvdlFM_.js";
 import "./chunks/index-CLIro-EG.js";
-import "./chunks/bookmark-state-C4vetoa0.js";
-import { I as fe } from "./chunks/use-create-flow-overlay-state-DZBZiiD-.js";
+import "./chunks/bookmark-state-Cu-a5ie_.js";
+import { I as fe } from "./chunks/use-create-flow-overlay-state-CbGIjaVD.js";
 import { C as me } from "./chunks/x-4f5U2XwU.js";
 import "./chunks/appearance-runtime-provider-B-M8gwlZ.js";
 const he = { cssWidth: 960, cssHeight: 540 };

package/dist/surfboard/index.js

@@ -1,5 +1,5 @@
-import { a, R as s, D as o } from "../chunks/report-preferences-dialog-4QEZWe5U.js";
-import { C as f, E as D } from "../chunks/table-settings-CunhoDUi.js";
+import { a, R as s, D as o } from "../chunks/report-preferences-dialog-CM7kXmXp.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/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

@@ -1,7 +1,10 @@
 /**
- * Preview screen sizes without editing (responsive layouts RL-D19): opens the
- * sheet's floating size control, look-only, at the size the grid shows now.
- * 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.
+ * 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,7 +1,7 @@
-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-CunhoDUi.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-C4vetoa0.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 = [

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';
 };
-export type DashboardFilterMappingDraftStatus = 'pendingSource' | 'automatic' | 'suggested' | 'needsMapping' | 'mapped' | 'notApplicable' | 'excluded' | 'invalidMapping' | 'metadataUnavailable';
-export type DashboardFilterMappingDraftRow = {
+/** 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'>;
+};
+/** 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,150 @@ 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. `muted`: the field
+ * doesn't apply yet (a suggestion), so all of it reads quiet.
+ */
+ | {
+    kind: 'field';
+    target: DashboardFilterFieldTarget;
+    prefix?: 'Auto' | 'Suggested';
+    muted?: true;
+}
+/** 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;
+    /**
+     * Colour means something needs fixing (relationship filter reach R-31):
+     * `review` (amber) a field must be chosen before saving, `invalid` (red) a
+     * decision that no longer runs. Everything else is `quiet`, offers too.
+     */
+    tone: 'quiet' | 'review' | 'invalid';
+    /**
+     * How the row counts in the summary: applied, an open offer (a suggested
+     * field, a path to choose), not applied, a field to choose, or invalid;
+     * none while its source or the server's answer is pending.
+     */
+    count?: 'covered' | 'suggested' | 'pathChoice' | 'excluded' | 'needsChoice' | 'invalid';
+    /** Something breaks or blocks saving: a field to choose, or invalid. The Cards tab dot and the chip warning. */
+    attention: boolean;
+    /** A suggested field the row offers to use in one click ("Use"). */
+    suggestion?: DashboardFilterFieldTarget;
+    /** 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;
@@ -64,9 +352,15 @@ export type DashboardFilterMappingAcceptance = {
 };
 export type DashboardFilterMappingStatusSummary = {
     coveredCount: number;
-    reviewCount: number;
+    /** Cards with a suggested field to use; they aren't filtered until it's used. */
+    suggestedCount: number;
+    /** Cards with equally preferred paths; they aren't filtered until one is chosen. */
+    pathChoiceCount: number;
     excludedCount: number;
+    /** Cards that need a field chosen before the mapping can be saved. */
+    needsChoiceCount: number;
     invalidCount: number;
+    /** What breaks or blocks saving (needs a field, invalid): the Cards tab dot and the chip warning. */
     attentionCount: number;
 };
 export type DashboardFilterMappingDraft = {
@@ -99,6 +393,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 +410,47 @@ 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;
+/**
+ * What breaks or blocks saving, in words, for the chip warning, the Cards
+ * tab dot and the popover footer (relationship filter reach R-31). Absent
+ * when nothing does.
+ */
+export declare function describeDashboardFilterMappingAttention(summary: DashboardFilterMappingStatusSummary): {
+    tone: 'invalid' | 'review';
+    text: string;
+} | undefined;
+/**
+ * Open offers, in words, for the popover footer: cards that aren't filtered
+ * until the author uses a suggestion or chooses a path. Information, not a
+ * warning (R-31). Absent when there are none.
+ */
+export declare function describeDashboardFilterMappingOffers(summary: DashboardFilterMappingStatusSummary): string | undefined;
 /**
  * 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 +460,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 {};