react-semaphor 0.1.546 → 0.1.548

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

@@ -10,9 +10,18 @@ export declare function isDashboardFilterOperationCompatible(dataType: unknown,
 export declare const DASHBOARD_FILTER_OPERATIONS: ReadonlySet<string>;
 export type DashboardFilterScalarType = keyof typeof OPERATIONS_BY_DATA_TYPE;
 /**
- * The values a filter operation takes: how many, and of which scalar type.
  * The one rule for stored filter values, in authored defaults and in saved
- * bookmarks. Appends a message naming `location` for the first problem.
+ * bookmarks: the values a filter operation takes (how many, and of which
+ * scalar type), and a date window that runs to now. A dashboard filter's
+ * dates never count back from the latest data (relationship filter reach
+ * RF-INV-13): the Cards tab previews reach without a value, and a route can't
+ * carry a data anchor (P-6, ledger R-15). MCP edits already refuse such a
+ * default. Appends a message naming `location` (the stored value) for the
+ * first problem.
  */
-export declare function validateDashboardFilterValues(operation: unknown, values: readonly unknown[], valueType: DashboardFilterScalarType | undefined, location: string, errors: string[]): void;
+export declare function validateDashboardFilterValues(value: {
+    operation: unknown;
+    values: readonly unknown[];
+    relativeMeta?: unknown;
+}, valueType: DashboardFilterScalarType | undefined, location: string, errors: string[]): void;
 export {};

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

@@ -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.548",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",