react-semaphor 0.1.546 → 0.1.547

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

@@ -48,10 +48,14 @@ 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, type DashboardFilterCardReach } from '../../lib/query-context/dashboard-filter-mapping-resolution.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/outline/outline-dashboard.d.ts

@@ -1,3 +1,4 @@
+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';
@@ -26,6 +27,12 @@ export type OutlineViewer = {
     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;

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

@@ -1,4 +1,6 @@
 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';
@@ -35,11 +37,12 @@ export type OutlineFilter = {
     reaches: string[];
     /** Card ids excluded explicitly. */
     excluded: string[];
-    /** In scope, not matched. */
+    /** 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<{
@@ -47,6 +50,16 @@ export type OutlineFilter = {
         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;
@@ -63,6 +76,15 @@ export type OutlineFilter = {
         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
@@ -71,8 +93,8 @@ export type OutlineFilter = {
  * resolves to.
  */
 export declare function outlineCalendar(calendar: CalendarContext | undefined, updatedAt: string | undefined): CalendarContext;
-export declare function summarizeFilter(dashboard: TDashboard, entry: FilterInputEntry, calendar?: CalendarContext): OutlineFilter;
+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): OutlineFilter[];
+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): OutlineFilter | undefined;
+export declare function outlineFilter(dashboard: TDashboard, filterId: string, calendar?: CalendarContext, options?: OutlineReachOptions): OutlineFilter | undefined;

package/dist/types/shared/dashboard-authoring/semantic-auto-join-card.d.ts

@@ -0,0 +1,22 @@
+import { TFilterValue } from '../../components/surfboard/filter/types.js';
+import { TCard } from '../../lib/types/common-types.js';
+/**
+ * Where relationship filter reach runs (relationship filter reach RF-D18): a
+ * card on a semantic domain with no explicit join plan. The join plan is read
+ * as the card's filter source index reads it: a Matrix card's from its spec,
+ * every other card's from its config. The browser decides only whether to
+ * send a value (`decideDashboardFilterCardTarget`, `relationship`); the server
+ * decides reach through the domain's relationships. Both call this.
+ */
+export declare function isSemanticAutoJoinCard(card: Pick<TCard, 'type' | 'dataSource' | 'config'> & {
+    sql?: string;
+    python?: string;
+}): boolean;
+/**
+ * The one semantic dataset a filter value's field reads, with its domain:
+ * undefined when the value names no dataset, several, or no semantic domain.
+ */
+export declare function filterValueSemanticDataset(value: Pick<TFilterValue, 'fieldMeta' | 'semanticContext'>): {
+    domainId: string;
+    datasetName: string;
+} | undefined;

package/package.json

@@ -5,7 +5,7 @@
     "email": "support@semaphor.cloud"
   },
   "license": "MIT",
-  "version": "0.1.546",
+  "version": "0.1.547",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",