react-semaphor 0.1.552 → 0.1.553

package/dist/surfboard/index.js

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

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-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";
+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-CBm7G0yx.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-BdBzm_EV.js";
+import { D as q } from "../chunks/token-types-B1p9F_wS.js";
+import { B as Q, a as j, p as W, r as J } from "../chunks/bookmark-state-aGO7_ryE.js";
+import { r as H, a as Z } from "../chunks/pivot-result-identity-dZIYsMrY.js";
+import { D as ee } from "../chunks/report-runtime-context-CKiIubIu.js";
 const e = [
   "concatenate",
   "conditional-category",

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

@@ -11,5 +11,8 @@ import { TDashboard } from '../types/common-types.js';
  * 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).
+ * Last, every Pivot and Hierarchical card the converter can carry exactly
+ * loads as a Matrix card (pivot-aggregate-to-matrix PM-D1, PM-D3): in memory
+ * only, stored as Matrix when someone saves.
  */
 export declare function prepareLoadedDashboard<TDashboardShape extends TDashboard>(dashboard: TDashboardShape): TDashboardShape;

package/dist/types/lib/utils/card-config-utils.d.ts

@@ -0,0 +1,61 @@
+import { CardConfig, DataSource, Field, FilterGroup, JoinPlan } from '../types/explorer-types.js';
+import { TCard } from '../types/common-types.js';
+/** Matrix acquisition requires its structured definition, never an authored SQL query. */
+export declare function supportsSqlEditor(cardType: TCard['type']): boolean;
+export declare function hasEditorResultsView(cardType: TCard['type']): boolean;
+export declare function hasEditorInfoView(cardType: TCard['type']): boolean;
+/** The deprecated table types every saved card of which loads as Matrix (pivot-aggregate-to-matrix). */
+export declare const LEGACY_TABLE_CARD_TYPES: readonly ["pivotTable", "aggregateTable"];
+export type LegacyTableCardType = (typeof LEGACY_TABLE_CARD_TYPES)[number];
+export declare function isLegacyTableCard(card: Pick<TCard, 'type'>): card is Pick<TCard, 'type'> & {
+    type: LegacyTableCardType;
+};
+/**
+ * Why one data part did not carry exactly (pivot-aggregate-to-matrix PM-D12).
+ * The problem-area codes (PA-n) are the shapes a later rule will translate;
+ * display differences are never gaps (PM-D15).
+ */
+export type CardTypeChangeGapCode = 'calculated_metric_per_row' | 'calculated_metric_without_stage' | 'calculated_field_card_scope' | 'calculated_field_dashboard_scope' | 'source_field_renamed' | 'join_not_carried' | 'metric_parameters' | 'aggregate_not_supported' | 'unknown_field_property' | 'calculated_level_without_inputs' | 'field_not_resolvable' | 'filter_not_accepted' | 'control_binding' | 'no_shelf_fields' | 'matrix_definition_incomplete' | 'detail_columns' | 'matrix_field_not_on_shelves' | 'not_in_detail_table';
+export type CardTypeChangeGap = {
+    code: CardTypeChangeGapCode;
+    label: string;
+};
+export type MatrixRepresentationChange = {
+    card: Partial<TCard>;
+    /** Authored data parts the next representation does not accept, in shelf order. */
+    gaps: readonly CardTypeChangeGap[];
+};
+/**
+ * Crossing the Matrix boundary carries the card's authored definition (MS-D12):
+ * rows, pivot columns, metrics, the join and filters are read once through
+ * `getCardDefinition` and written into the next representation by each part's
+ * own writer. A data part the next representation refuses is a gap. Into
+ * Matrix, number formats carry, and from a Pivot or Hierarchical card the
+ * expansion and the visible totals too (PM-D5); every other display setting
+ * takes the Matrix defaults. SQL, Python and control bindings start fresh.
+ * Needs the loaded column catalog to complete join keys and resolve Matrix
+ * fields; without it, keys saved with their identity still carry.
+ */
+export declare function convertMatrixRepresentation(card: TCard, nextType: TCard['type'], catalog?: readonly Field[], 
+/** Mints each carried Matrix field's instance id; a replayed conversion passes stored ids (DE-D54). */
+createId?: () => string): MatrixRepresentationChange;
+/** The switch reads the catalog only when it has something to carry. */
+export declare function matrixSwitchNeedsCatalog(card: TCard, nextType: TCard['type']): boolean;
+/** Replacing the base dataset starts a new definition; metadata refresh does not. */
+export declare function withAuthoredCardDataSource(card: TCard, dataSource: DataSource): Partial<TCard>;
+export declare function getAuthoredCardJoinPlan(card: Pick<TCard, 'type' | 'config'>): JoinPlan | undefined;
+/** The normal join editor writes the canonical definition, including empty drafts. */
+export declare function withAuthoredCardJoinPlan(card: Pick<TCard, 'type' | 'config' | 'dataSource'>, joinPlan: JoinPlan | undefined): CardConfig;
+/** Authored predicates from the card's canonical representation. */
+export declare function getAuthoredCardFilters(card: Pick<TCard, 'type' | 'config'> | undefined): FilterGroup | undefined;
+export declare function withAuthoredCardFilters(card: Pick<TCard, 'type' | 'config' | 'dataSource'>, filters: FilterGroup | undefined): CardConfig;
+/**
+ * Checks if a card config object has actual configuration data
+ * An empty config object {} should be treated as no config
+ */
+export declare function hasValidCardConfig(config: CardConfig | undefined, cardType?: TCard['type']): boolean;
+type CardSetupCheckOptions = {
+    skipSetupCheck?: boolean;
+};
+export declare function isCardUnconfigured(card: Pick<TCard, 'type' | 'sql' | 'config' | 'connectionId' | 'dataSource' | 'customCardPreferences'>, options?: CardSetupCheckOptions): boolean;
+export {};

package/dist/types/lib/utils/card-type-change.d.ts

@@ -1,5 +1,7 @@
 import { TCard, TCardPreferences, TCustomCardPreferences } from '../types/common-types.js';
 import { Field } from '../types/explorer-types.js';
+import { CardTypeChangeGap } from './card-config-utils.js';
+export type { CardTypeChangeGap, CardTypeChangeGapCode } from './card-config-utils.js';
 export declare function sharedCardPreferences(preferences: TCardPreferences | undefined): TCardPreferences;
 export type CardTypeChangeOptions = {
     /** The loaded column catalog; the Matrix carry resolves fields against it. */
@@ -22,7 +24,9 @@ export type CardTypeChange = {
 } | {
     status: 'changed';
     card: TCard;
-    /** Labels of authored parts the new type could not keep. */
+    /** Authored data parts the new type could not keep, with why (pivot-aggregate-to-matrix PM-D12). */
+    gaps: readonly CardTypeChangeGap[];
+    /** The gaps' labels, in the same order, for readers that only name them. */
     leftOut: readonly string[];
     /** Chart-scoped preference keys the new type drops (DE-D43). */
     droppedPreferences: readonly (keyof TCardPreferences)[];

package/dist/types/shared/analytics-protocol/explorer-input-schemas.d.ts

@@ -1,5 +1,7 @@
 import { z } from 'zod';
 import { Field, FilterGroup, JoinPlan } from '../../lib/types/explorer-types.js';
+/** The roles a field may carry; the Matrix carry drops any other (pivot-aggregate-to-matrix PA-19). */
+export declare const explorerFieldRoleSchema: z.ZodEnum<["groupby", "metric", "sortby", "pivotby", "detail"]>;
 export declare const explorerFieldSchema: z.ZodType<Field>;
 export declare const filterGroupSchema: z.ZodType<FilterGroup>;
 export declare const joinPlanSchema: z.ZodType<JoinPlan>;

package/dist/types/shared/dashboard-authoring/document-section-cards.d.ts

@@ -44,6 +44,12 @@ export type DashboardCardLocation = {
  * then frame cards, then document section cards (every KPI card included).
  */
 export declare function listDashboardCardLocations(dashboard: Pick<TDashboard, 'sheets'>): readonly DashboardCardLocation[];
+/**
+ * The dashboard with each card mapped, in `listDashboardCardLocations` order.
+ * Returns the input object when no card changed, and likewise each sheet,
+ * frame and section, so callers can compare by reference.
+ */
+export declare function mapDashboardCards<T extends Pick<TDashboard, 'sheets'>>(dashboard: T, map: (card: TCard, location: DashboardCardLocation) => TCard): T;
 export type DocumentSectionShapeIssue = {
     /** Path relative to the section, for example `cards[2].type`. Empty for the section itself. */
     path: string;

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

@@ -9,6 +9,7 @@ export * from './temporal-bucket-authoring.js';
 export * from './canonical-result-keys.js';
 export * from './dashboard-card-source-index.js';
 export * from './document-section-cards.js';
+export * from './legacy-table-routing.js';
 export * from './dashboard-filter-mapping-types.js';
 export * from './dashboard-filter-automatic-target.js';
 export * from './dashboard-filter-sql-subscription.js';

package/dist/types/shared/dashboard-authoring/legacy-table-routing.d.ts

@@ -0,0 +1,64 @@
+import { TCard, TDashboard, TFrame } from '../../lib/types/common-types.js';
+import { CardTypeChangeGap } from '../../lib/utils/card-type-change.js';
+import { DashboardCardLocation } from './document-section-cards.js';
+export { LEGACY_TABLE_CARD_TYPES, isLegacyTableCard, type LegacyTableCardType, } from '../../lib/utils/card-config-utils.js';
+/**
+ * Load routing of Pivot and Hierarchical cards
+ * (semaphor-app docs/implementation-plans/pivot-aggregate-to-matrix). A saved
+ * `pivotTable` or `aggregateTable` card is converted in memory by the one
+ * converter and replaced only when the conversion is exact: no gap, and a
+ * ready definition (PM-D3). A Pivot that only groups rows becomes the regular
+ * Table; every other card becomes Matrix (`legacyTableRoutingTarget`).
+ * Nothing is written back; a save stores the new card like any other edit
+ * (PM-D1). This module never builds a definition itself (PM-D2).
+ */
+/** PM-D7: the namespace of the ids routing mints. Fixed forever: changing it changes every routed card. */
+export declare const LEGACY_TABLE_ROUTING_ID_NAMESPACE = "9677efdd-86ec-4afb-b9bb-5ead8b5442af";
+/**
+ * The ids a routed card's Matrix levels and measures get: the n-th call
+ * returns the UUID v5 of `${cardId}#${n}`. The same saved card therefore
+ * converts to the same Matrix definition on every load, in the browser and
+ * on the server (PM-D7).
+ */
+export declare function legacyTableRoutingIds(cardId: string): () => string;
+export type LegacyTableCardRouting = 
+/** Not a Pivot or Hierarchical card: the input object. */
+{
+    status: 'not_legacy';
+    card: TCard;
+}
+/** The converter's Matrix or Table card, same card id. */
+ | {
+    status: 'routed';
+    card: TCard;
+}
+/** The input object, kept as stored, with what blocked the conversion. */
+ | {
+    status: 'unrouted';
+    card: TCard;
+    gaps: readonly CardTypeChangeGap[];
+};
+/**
+ * PM-D3 target: a Pivot driven by its shelves (no SQL text, at least one row
+ * level or metric) with no pivot columns and no
+ * row or column totals is a flat grouped table, so it becomes the regular
+ * Table (the editor's table-kind switch keeps its config unchanged, and the
+ * query builder compiles the same SQL for both types). Every other Pivot and
+ * every Hierarchical card becomes Matrix.
+ */
+export declare function legacyTableRoutingTarget(card: TCard): 'table' | 'matrixTable';
+/** One card: route it when the conversion is exact (PM-D3). */
+export declare function routeLegacyTableCard(card: TCard): LegacyTableCardRouting;
+/** Each card of a library frame. Returns the input object when nothing routed. */
+export declare function routeLegacyTableFrame<T extends Pick<TFrame, 'cards'>>(frame: T): T;
+export type UnroutedLegacyTableCard = {
+    location: DashboardCardLocation;
+    gaps: readonly CardTypeChangeGap[];
+};
+export type LegacyTableDashboardRouting<T> = {
+    /** The input object when nothing routed. */
+    dashboard: T;
+    unrouted: readonly UnroutedLegacyTableCard[];
+};
+/** Every sheet, frame and document section card of a dashboard. */
+export declare function routeLegacyTableCards<T extends Pick<TDashboard, 'sheets'>>(dashboard: T): LegacyTableDashboardRouting<T>;

package/package.json

@@ -5,7 +5,7 @@
     "email": "support@semaphor.cloud"
   },
   "license": "MIT",
-  "version": "0.1.552",
+  "version": "0.1.553",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",
@@ -127,7 +127,7 @@
     "build": "node scripts/build.mjs",
     "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
     "lint:regressions": "node scripts/lint-regressions.mjs",
-    "check:guards": "node scripts/card-config-consumers.mjs && node scripts/components-entry-imports.mjs && node scripts/types-entry-imports.mjs && node scripts/card-query-assembly-imports.mjs && node scripts/assistant-chat-imports.mjs && node scripts/filter-model-reads.mjs && node scripts/layout-engine.mjs",
+    "check:guards": "node scripts/card-config-consumers.mjs && node scripts/components-entry-imports.mjs && node scripts/types-entry-imports.mjs && node scripts/card-query-assembly-imports.mjs && node scripts/matrix-conversion-imports.mjs && node scripts/assistant-chat-imports.mjs && node scripts/filter-model-reads.mjs && node scripts/layout-engine.mjs",
     "preview": "vite preview",
     "test": "vitest run",
     "test:changed": "vitest run --changed",