react-semaphor 0.1.544 → 0.1.546

package/dist/types/shared/dashboard-authoring/changes/card-query-part.d.ts

@@ -0,0 +1,487 @@
+import { TCard } from '../../../lib/types/common-types.js';
+import { TChartType } from '../../../lib/charts/types.js';
+import { CardConfig, DataSource, DetailField, Field, GroupByField, MetricField, SortByField } from '../../../lib/types/explorer-types.js';
+import { MatrixConfig } from '../../analytics-protocol/matrix-definition-contract.js';
+import { CardQueryForm } from './card-types.js';
+import { CardQuery, FieldRef, MatrixColumns, MetricCardQuery, RecordsCardQuery } from './dashboard-change.js';
+/**
+ * A card is two things: what it computes (its query part) and how it looks
+ * (everything else). `requery` replaces the first and carries the second, so
+ * a query change keeps every label, format and setting it doesn't name
+ * (MCP dashboard editing SPEC 3.4, DE-D38, DE-D51, DE-INV-11). A change to a
+ * stored card replaces only the parts of its query it states; every other
+ * part keeps its stored form byte for byte (DE-D61).
+ */
+export declare const CARD_QUERY_CONFIG_KEYS: readonly ["metricColumns", "groupByColumns", "pivotByColumns", "sortByColumns", "detailColumns", "queryBaseSource", "filters", "joinPlan", "rowLimit", "matrix"];
+export type CardQueryConfigKey = (typeof CARD_QUERY_CONFIG_KEYS)[number];
+/** A column's role and field identity, plus its position among columns of the same role and field. */
+export type ColumnKey = {
+    role: 'metric' | 'group_by' | 'detail';
+    field: string;
+    ordinal: number;
+};
+export type CardQueryPart = {
+    /** The type this part was compiled for; must equal the card's type when applied. */
+    type: TChartType;
+    source: {
+        kind: 'semantic';
+        dataSource: DataSource;
+        connectionId: string;
+    } | {
+        kind: 'sql';
+        connectionId: string;
+        sql: string;
+    };
+    /** Only the query keys of CardConfig; undefined for SQL. */
+    config?: Pick<CardConfig, CardQueryConfigKey>;
+    /**
+     * Columns whose label the change stated (a field ref's label); those labels
+     * win over carried ones. For a Matrix, `metric` keys name measures and
+     * `group_by` keys name levels (`matrixColumnKeys`).
+     */
+    statedLabels?: ColumnKey[];
+    /** What a change to a stored card states (DE-D61); absent, the part states everything. */
+    change?: QueryChange;
+};
+/** The parts of a card's query a `card.update` can state. */
+export declare const QUERY_ASPECTS: readonly ["measures", "groupings", "columns", "filters", "order", "limit"];
+export type QueryAspect = (typeof QUERY_ASPECTS)[number];
+/**
+ * What a query change states differently from the card's read query.
+ * `requery` rebuilds only these aspects from the compiled part; every other
+ * part keeps its stored config byte for byte, and within a rebuilt aspect
+ * whatever the change left as it was keeps its stored form too. A part
+ * without one states everything: a new card, a new source or form, SQL.
+ */
+export type QueryChange = {
+    aspects: QueryAspect[];
+    /** Finer facts a structural control's override is checked against (`controlRefusal`). */
+    parts: {
+        /** A measure's stated aggregate differs from what it read, or a new measure states one. */
+        measureAggregates: boolean;
+        /** The dimensions (fields, in order) differ. */
+        dimensions: boolean;
+        /** The grouped date's grain differs. */
+        timeGrain: boolean;
+    };
+    /**
+     * Columns the change left exactly as they read (role, field, occurrence): in
+     * a rebuilt aspect each must come back as its stored column, else the reading
+     * didn't compile back to what the card stores and the change is refused.
+     */
+    keptColumns: ColumnKey[];
+    /** Filters the change left as they were, by condition id: each keeps its stored condition. */
+    keptFilterIds: string[];
+    /** The change left the date window as it was: it keeps its stored condition. */
+    keptWindow: boolean;
+    /**
+     * The stored card's order is a choice (its read query states `orderBy`).
+     * Otherwise it is the compiler's default or none, and a default follows the
+     * query: rebuilt when the measures, groupings, columns or limit change.
+     */
+    orderChosen: boolean;
+};
+/**
+ * The aspect that owns each query config key. `source` keys (the base source
+ * and joins, with the card's data source) follow the datasets the card's
+ * fields use; a Matrix is split by aspect inside its spec.
+ */
+export declare const QUERY_CONFIG_KEY_ASPECTS: {
+    readonly metricColumns: "measures";
+    readonly groupByColumns: "groupings";
+    readonly pivotByColumns: "groupings";
+    readonly detailColumns: "columns";
+    readonly filters: "filters";
+    readonly sortByColumns: "order";
+    readonly rowLimit: "limit";
+    readonly queryBaseSource: "source";
+    readonly joinPlan: "source";
+    readonly matrix: "matrix";
+};
+/** Deep equality of stored values, independent of key order; `undefined` and absent are equal. */
+export declare function sameValue(left: unknown, right: unknown): boolean;
+/** TCard: `query` keys are replaced by `requery`, `presentation` keys kept byte for byte. */
+export declare const CARD_KEY_CLASSES: {
+    readonly id: "presentation";
+    readonly title: "presentation";
+    readonly tabTitle: "presentation";
+    readonly displayTab: "presentation";
+    readonly description: "presentation";
+    readonly info: "presentation";
+    readonly connectionId: "query";
+    readonly datamodelId: "presentation";
+    readonly type: "query";
+    readonly sql: "query";
+    readonly python: "query";
+    readonly dataSource: "query";
+    readonly config: "query";
+    readonly interactionConfig: "presentation";
+    readonly linkedSourceCardId: "presentation";
+    readonly linkedReferenceOverrides: "presentation";
+    readonly linkedInteractionTargetOverrides: "presentation";
+    readonly clickToFilter: "presentation";
+    readonly respondsToSelections: "presentation";
+    readonly linkedClickToFilterOverrides: "presentation";
+    readonly paginationConfig: "presentation";
+    readonly queryConfig: "presentation";
+    readonly customCfg: "presentation";
+    readonly preferences: "presentation";
+    readonly customCardPreferences: "presentation";
+    readonly lastSelectedDatabase: "presentation";
+    readonly lastSelectedDatamodelId: "presentation";
+    readonly lastSelectedSchema: "presentation";
+    readonly lastSelectedTable: "presentation";
+    readonly refreshInterval: "presentation";
+    readonly displayPreferences: "presentation";
+    readonly inlineFilters: "presentation";
+    readonly calculatedFields: "presentation";
+    readonly controls: "presentation";
+    readonly controlBindings: "presentation";
+};
+/** CardConfig: the query keys are `CARD_QUERY_CONFIG_KEYS`; the rest are kept. */
+export declare const CARD_CONFIG_KEY_CLASSES: {
+    readonly matrix: "query";
+    readonly groupByColumns: "query";
+    readonly metricColumns: "query";
+    readonly pivotByColumns: "query";
+    readonly sortByColumns: "query";
+    readonly detailColumns: "query";
+    readonly queryBaseSource: "query";
+    readonly filters: "query";
+    readonly joinPlan: "query";
+    readonly rowLimit: "query";
+    readonly detailTableBackup: "presentation";
+    readonly summary: "presentation";
+    readonly rowAggregates: "presentation";
+    readonly columnAggregates: "presentation";
+};
+export declare const COLUMN_KEY_CLASSES: {
+    metric: {
+        readonly parameters: "query";
+        readonly aliasTemplate: "presentation";
+        readonly valueAliases: "presentation";
+        readonly isPreAggregated: "query";
+        readonly semanticAggregate: "query";
+        readonly effectiveAggregate: "query";
+        readonly aggregateSource: "query";
+        readonly comparison: "presentation";
+        readonly comparisonPolarity: "presentation";
+        readonly semanticComparisonPolarity: "query";
+        readonly id: "presentation";
+        readonly name: "query";
+        readonly label: "presentation";
+        readonly derivedLabel: "presentation";
+        readonly alias: "query";
+        readonly sourceField: "query";
+        readonly source: "query";
+        readonly qualifiedFieldName: "query";
+        readonly dataType: "query";
+        readonly nativeDataType: "query";
+        readonly description: "query";
+        readonly qualifiedEntityName: "query";
+        readonly dateFormat: "presentation";
+        readonly customFormat: "presentation";
+        readonly granularity: "query";
+        readonly entityId: "query";
+        readonly entityName: "query";
+        readonly entityType: "query";
+        readonly role: "query";
+        readonly expression: "query";
+        readonly calculatedFormula: "query";
+        readonly derivedField: "query";
+        readonly format: "presentation";
+        readonly semanticTemporalPresentation: "presentation";
+        readonly aggregate: "query";
+        readonly aggregateOrigin: "query";
+        readonly calculationRepresentation: "query";
+        readonly calculatedFieldOrigin: "query";
+        readonly labelOrigin: "presentation";
+        readonly formatOrigin: "presentation";
+        readonly fieldScope: "query";
+    };
+    group_by: {
+        readonly timeDrillPath: "presentation";
+        readonly id: "presentation";
+        readonly name: "query";
+        readonly label: "presentation";
+        readonly derivedLabel: "presentation";
+        readonly alias: "query";
+        readonly sourceField: "query";
+        readonly source: "query";
+        readonly qualifiedFieldName: "query";
+        readonly dataType: "query";
+        readonly nativeDataType: "query";
+        readonly description: "query";
+        readonly qualifiedEntityName: "query";
+        readonly dateFormat: "presentation";
+        readonly customFormat: "presentation";
+        readonly granularity: "query";
+        readonly entityId: "query";
+        readonly entityName: "query";
+        readonly entityType: "query";
+        readonly role: "query";
+        readonly expression: "query";
+        readonly calculatedFormula: "query";
+        readonly derivedField: "query";
+        readonly format: "presentation";
+        readonly semanticTemporalPresentation: "presentation";
+        readonly aggregate: "query";
+        readonly aggregateOrigin: "query";
+        readonly calculationRepresentation: "query";
+        readonly calculatedFieldOrigin: "query";
+        readonly labelOrigin: "presentation";
+        readonly formatOrigin: "presentation";
+        readonly fieldScope: "query";
+    };
+    detail: {
+        readonly id: "presentation";
+        readonly name: "query";
+        readonly label: "presentation";
+        readonly derivedLabel: "presentation";
+        readonly alias: "query";
+        readonly sourceField: "query";
+        readonly source: "query";
+        readonly qualifiedFieldName: "query";
+        readonly dataType: "query";
+        readonly nativeDataType: "query";
+        readonly description: "query";
+        readonly qualifiedEntityName: "query";
+        readonly dateFormat: "presentation";
+        readonly customFormat: "presentation";
+        readonly granularity: "query";
+        readonly entityId: "query";
+        readonly entityName: "query";
+        readonly entityType: "query";
+        readonly role: "query";
+        readonly expression: "query";
+        readonly calculatedFormula: "query";
+        readonly derivedField: "query";
+        readonly format: "presentation";
+        readonly semanticTemporalPresentation: "presentation";
+        readonly aggregate: "query";
+        readonly aggregateOrigin: "query";
+        readonly calculationRepresentation: "query";
+        readonly calculatedFieldOrigin: "query";
+        readonly labelOrigin: "presentation";
+        readonly formatOrigin: "presentation";
+        readonly fieldScope: "query";
+    };
+    sort: {
+        readonly direction: "query";
+        readonly id: "presentation";
+        readonly name: "query";
+        readonly label: "presentation";
+        readonly derivedLabel: "presentation";
+        readonly alias: "query";
+        readonly sourceField: "query";
+        readonly source: "query";
+        readonly qualifiedFieldName: "query";
+        readonly dataType: "query";
+        readonly nativeDataType: "query";
+        readonly description: "query";
+        readonly qualifiedEntityName: "query";
+        readonly dateFormat: "presentation";
+        readonly customFormat: "presentation";
+        readonly granularity: "query";
+        readonly entityId: "query";
+        readonly entityName: "query";
+        readonly entityType: "query";
+        readonly role: "query";
+        readonly expression: "query";
+        readonly calculatedFormula: "query";
+        readonly derivedField: "query";
+        readonly format: "presentation";
+        readonly semanticTemporalPresentation: "presentation";
+        readonly aggregate: "query";
+        readonly aggregateOrigin: "query";
+        readonly calculationRepresentation: "query";
+        readonly calculatedFieldOrigin: "query";
+        readonly labelOrigin: "presentation";
+        readonly formatOrigin: "presentation";
+        readonly fieldScope: "query";
+    };
+    pivot: {
+        readonly memberOrder: "presentation";
+        readonly id: "presentation";
+        readonly name: "query";
+        readonly label: "presentation";
+        readonly derivedLabel: "presentation";
+        readonly alias: "query";
+        readonly sourceField: "query";
+        readonly source: "query";
+        readonly qualifiedFieldName: "query";
+        readonly dataType: "query";
+        readonly nativeDataType: "query";
+        readonly description: "query";
+        readonly qualifiedEntityName: "query";
+        readonly dateFormat: "presentation";
+        readonly customFormat: "presentation";
+        readonly granularity: "query";
+        readonly entityId: "query";
+        readonly entityName: "query";
+        readonly entityType: "query";
+        readonly role: "query";
+        readonly expression: "query";
+        readonly calculatedFormula: "query";
+        readonly derivedField: "query";
+        readonly format: "presentation";
+        readonly semanticTemporalPresentation: "presentation";
+        readonly aggregate: "query";
+        readonly aggregateOrigin: "query";
+        readonly calculationRepresentation: "query";
+        readonly calculatedFieldOrigin: "query";
+        readonly labelOrigin: "presentation";
+        readonly formatOrigin: "presentation";
+        readonly fieldScope: "query";
+    };
+};
+/** Per column type, the attributes a paired column keeps (besides its id). */
+export declare const COLUMN_PRESENTATION_KEYS: {
+    readonly metric: string[];
+    readonly group_by: string[];
+    readonly detail: string[];
+};
+type ColumnRole = ColumnKey['role'];
+type Column = MetricField | GroupByField | DetailField;
+/** The dataset a column's field belongs to: its semantic source, else its entity. */
+export declare function columnDataset(field: Pick<Field, 'source' | 'entityName' | 'entityId'>): string;
+/** A field's identity from its name and dataset: the one key columns and field refs are compared by. */
+export declare function fieldIdentityKey(name: string, dataset: string): string;
+/** A column's field identity: its name and dataset (never its label). */
+export declare function columnFieldKey(field: Pick<Field, 'name' | 'source' | 'entityName' | 'entityId'>): string;
+/**
+ * The field of a catalog named `name` on `dataset`: the dataset's own field
+ * first, so a domain calculated field of the same name (listed first in the
+ * editor's catalog) never stands in for it; else any field of that name.
+ */
+export declare function findCatalogField<T extends Pick<Field, 'name' | 'source' | 'entityName' | 'entityId'>>(fields: readonly T[], name: string, dataset: string): T | undefined;
+export type ColumnPair = {
+    oldIndex: number;
+    newIndex: number;
+    pass: 1 | 2;
+};
+/**
+ * Pairs new columns with old ones of the same role: first the same field with
+ * the same aggregate or grain, in order; then the same field, in order (the
+ * aggregate or grain changed). Unpaired new columns are new; unpaired old
+ * columns are gone. Deterministic and total (S-INV-6a).
+ */
+export declare function matchColumns(role: ColumnRole, previous: readonly Column[], next: readonly Column[]): ColumnPair[];
+/**
+ * Each item's ColumnKey: its role, its field key, and which occurrence of that
+ * field it is among every item of the list. Labels, pairing and sorts all name
+ * a column this way, so a repeated field (a sum and an average of one measure)
+ * is never confused with its other occurrence.
+ */
+export declare function occurrenceKeys<T>(role: ColumnRole, items: readonly T[], key: (item: T) => string): ColumnKey[];
+/** The ColumnKey of each column in a list, in order. */
+export declare function columnKeys(role: ColumnRole, columns: readonly Column[]): ColumnKey[];
+/** A Matrix's levels (rows, then columns) and measures as ColumnKeys, in spec order. */
+export declare function matrixColumnKeys(matrix: MatrixConfig): {
+    levels: ColumnKey[];
+    measures: ColumnKey[];
+};
+export declare const sameColumnKey: (left: ColumnKey, right: ColumnKey) => boolean;
+/**
+ * The column a sort entry sorts by, by the one rule the query builder and the
+ * viewer resolve sorts with (`findSortTarget`), so what a card is read as
+ * sorting by is what its query sorts by.
+ */
+export declare function findSortedColumn(config: Pick<CardConfig, 'metricColumns' | 'groupByColumns' | 'detailColumns'>, sort: SortByField): Column | undefined;
+/** A field ref's name. */
+export declare function refName(ref: FieldRef): string;
+/** A field ref's dataset: its own, else the query's base dataset. */
+export declare function refDataset(ref: FieldRef, base: string): string;
+/** A field ref's identity: its name and dataset, however the base dataset is written (`fieldIdentityKey`). */
+export declare function refKey(ref: FieldRef, base: string): string;
+/** A query's form: measures, records (columns) or SQL. */
+export declare function queryForm(query: object | undefined): CardQueryForm | undefined;
+/** Whether a column or Matrix level is the grouped date: a date-like field with a grain (one rule for every reader and writer). */
+export declare function isGroupedDate(field: {
+    dataType?: string;
+} | undefined, grain: string | undefined): boolean;
+/** A label a change states, on the column it names. */
+export type StatedLabel = {
+    key: ColumnKey;
+    label: string;
+};
+/**
+ * Every label a query states, each on its ColumnKey, counted over every ref
+ * of its role, labelled or not (group_by: the dimensions, then a grouped
+ * date), so a label on the second of two measures of one field lands on the
+ * second.
+ */
+export declare function statedLabelsOf(query: MetricCardQuery | RecordsCardQuery): StatedLabel[];
+/** Whether a change rebuilds the columns of a role (else a label there is applied in place, `planCardLabels`). */
+export declare function rebuildsRole(change: QueryChange | undefined, role: ColumnKey['role']): boolean;
+/**
+ * What a patched query changes on the card it was read from, or undefined
+ * when it changes everything (a new source, form or SQL). An aspect changes
+ * when what it computes changes: field refs compare by identity (`refKey`)
+ * and stated aggregate, never by label, so a label alone changes no aspect
+ * and is applied to its column in place (`planCardLabels`), with nothing
+ * recompiled. The date field serves its grain and its window, so a new one
+ * belongs to whichever it serves (both when it serves neither).
+ */
+export declare function describeQueryChange(read: CardQuery, merged: CardQuery, readMatrix: MatrixColumns | undefined, matrix: MatrixColumns | undefined): QueryChange | undefined;
+/** The label a card shows for the column a ColumnKey names (a Matrix level or measure through its presentation). */
+export declare function labelAt(card: TCard, key: ColumnKey): string | undefined;
+/**
+ * The card with each stated label on the column it names, written by the
+ * label owner (`withAuthoredLabel`; on a Matrix, its presentation labels),
+ * and the labels that changed anything. A sort entry that copies a relabelled
+ * column follows it. Nothing is recompiled: a label is presentation.
+ */
+export declare function planCardLabels(card: TCard, labels: readonly StatedLabel[]): {
+    card: TCard;
+    changed: StatedLabel[];
+};
+/** A paired column whose aggregate or grain changed kept a label that differs from the field's own. */
+export type KeptLabel = {
+    label: string;
+    field: string;
+    role: ColumnRole;
+};
+export type CardRequery = {
+    ok: true;
+    card: TCard;
+    keptLabels: KeptLabel[];
+    /** Control bindings the change leaves without a target (a Matrix level or measure it removed), by control id. */
+    droppedBindings: string[];
+} | {
+    ok: false;
+    code: 'query_type_mismatch' | 'query_invalid';
+    message: string;
+}
+/** The change would alter a part of the card it doesn't state (DE-D61); `parts` names them. */
+ | {
+    ok: false;
+    code: 'query_not_kept';
+    message: string;
+    parts: string[];
+};
+/**
+ * `requery`'s one owner: the reducer applies it and the resolver reads its
+ * kept labels for `label_kept_after_change`. Without a `change` (a new card,
+ * a new source or form) the query part replaces the card's query keys; every
+ * other card field and config key is kept, and each paired column keeps its
+ * id and presentation (S-INV-5). With one (DE-D61), only the aspects it
+ * states are rebuilt: the rest keep their stored config, a column the change
+ * left as it was keeps its stored form, sorts follow their columns, and the
+ * result is checked against the stored card, so a part the change doesn't
+ * state never changes.
+ */
+export declare function planCardRequery(card: TCard, part: CardQueryPart): CardRequery;
+/**
+ * A change to a part of a chart or table that a control on it replaces at run
+ * time (`structuralControlOverride`) wouldn't take effect, so it is refused;
+ * every other part still changes (a measure added under an aggregation
+ * control, a dimension under a grain control). `relabelled` names the roles
+ * whose labels the change sets in place. A Matrix's controls each target one
+ * level or measure and are checked against it (`rebaseMatrix`). The resolver
+ * asks before compiling; `planCardRequery` asks again at apply.
+ */
+export declare function controlRefusal(card: TCard, change: QueryChange | undefined, relabelled?: readonly ColumnKey['role'][]): Extract<CardRequery, {
+    code: 'query_not_kept';
+}> | undefined;
+export {};

package/dist/types/shared/dashboard-authoring/changes/card-types.d.ts

@@ -0,0 +1,34 @@
+import { TChartType } from '../../../lib/charts/types.js';
+/**
+ * The card types an agent may set, and their rules (MCP dashboard editing
+ * DE-D20, DE-D43). Public names are snake_case; each maps to one stored chart
+ * type. Every other chart type still has a public name, for reading.
+ */
+export declare const CARD_TYPES: readonly ["kpi", "bar", "line", "area", "pie", "table", "detail_table", "matrix"];
+export type CardType = (typeof CARD_TYPES)[number];
+/** The three query forms a card can be written in. */
+export type CardQueryForm = 'measures' | 'records' | 'sql';
+export type CardTypeRule = {
+    chartType: TChartType;
+    /** The query forms this type accepts. */
+    forms: readonly CardQueryForm[];
+    /** A measures query's measure count. */
+    measures?: {
+        min: number;
+        max?: number;
+    };
+    /** False when a measures query may not have dimensions. */
+    dimensions: boolean;
+    /** True when the change must say which fields run across the top (`matrix.columns`). */
+    matrixColumns: boolean;
+};
+export declare const CARD_TYPE_RULES: Record<CardType, CardTypeRule>;
+export declare function isCardType(value: unknown): value is CardType;
+/** The stored chart type of a settable card type. */
+export declare function toChartType(type: CardType): TChartType;
+/** Every chart type's public snake_case name (`detailTable` is `detail_table`, `matrixTable` is `matrix`). */
+export declare function toPublicCardType(chartType: TChartType | string | undefined): string;
+/** The settable card type a chart type is, or undefined when it is not one of the eight. */
+export declare function settableCardType(chartType: TChartType | string | undefined): CardType | undefined;
+/** A chart type as a sentence names it ("bar chart", "detail table", "KPI"). */
+export declare function cardTypeSentenceName(chartType: TChartType | string | undefined): string;