react-semaphor 0.1.537 → 0.1.539

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

@@ -25,9 +25,14 @@ export * from './matrix-definition.js';
 export * from './matrix-authoring.js';
 export * from './field-aggregations.js';
 export * from './control-value-resolution.js';
+export * from './control-execution-contract.js';
+export * from './resolved-primary-date-field-validation.js';
+export * from './card-query-request.js';
 export * from './calculated-field-identity.js';
 export * from './calculated-field-placement.js';
 export * from './matrix-control-resolution.js';
 export { readMatrixCardConfig, matrixDefinitionFields, matrixDefinitionSources } from './matrix-card.js';
 export { matrixCatalogSources, matrixExecutionSources } from './matrix-control-sources.js';
 export * from './dashboard-option-dependencies.js';
+export * from './new-card.js';
+export * from './operations/apply-dashboard-operations.js';

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

@@ -0,0 +1,10 @@
+import { TCard } from '../../lib/types/common-types.js';
+/**
+ * The type a card starts as before anyone picks one: a table shows any mix of
+ * fields, where a chart needs a specific shape (P4-11). Clear returns a card
+ * to it. Saved cards keep their own type.
+ */
+export declare const NEW_CARD_TYPE = "table";
+export type NewCardInput = Pick<TCard, 'id' | 'title'> & Partial<Pick<TCard, 'description' | 'tabTitle' | 'connectionId' | 'dataSource' | 'preferences'>>;
+/** The one assembly of an empty card; callers pass their differences in. */
+export declare function createNewCard({ preferences, ...input }: NewCardInput): TCard;

package/dist/types/shared/dashboard-authoring/operations/apply-dashboard-operations.d.ts

@@ -0,0 +1,40 @@
+import { TDashboard, TFrame } from '../../../lib/types/common-types.js';
+/**
+ * Edits to a dashboard as operations on one pure reducer (analytics agent
+ * Plan 1, AG-D14, Phase 7a). Every writer of these edits calls it: the
+ * store's actions in the browser, and later an API or MCP edit on the
+ * server. Callers that differ pass their differences in (placement, ids);
+ * none keeps its own copy of the edit.
+ */
+/** Where a new frame goes on its sheet: first, last, or right after a frame and beside it. */
+export type DashboardFramePlacement = 'start' | 'end' | {
+    beside: string;
+};
+export type DashboardOperation = {
+    op: 'frame.add';
+    sheetId: string;
+    /** The frame with its cards, ids included. */
+    frame: TFrame;
+    /** Default `end`. */
+    placement?: DashboardFramePlacement;
+};
+export type DashboardOperationFailureCode = 'sheet_not_found'
+/** A document sheet places cards through its document, not its grid. */
+ | 'sheet_not_a_grid' | 'frame_id_taken';
+export type DashboardOperationResult = {
+    ok: true;
+    dashboard: TDashboard;
+} | {
+    ok: false;
+    failedAt: {
+        index: number;
+        op: DashboardOperation['op'];
+        code: DashboardOperationFailureCode;
+        message: string;
+    };
+};
+/**
+ * Applies the operations in order, all or nothing. Never changes its input:
+ * the result shares every sheet it did not touch.
+ */
+export declare function applyDashboardOperations(dashboard: TDashboard, operations: DashboardOperation[]): DashboardOperationResult;

package/dist/types/shared/dashboard-authoring/resolved-primary-date-field-validation.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The shape check of a request's resolved primary date field (the semantic
+ * model's primary date the card query assembly sends). One owner for the
+ * query route, CSV export and the card replay parser.
+ */
+export type ResolvedPrimaryDateFieldIssue = {
+    path: string;
+    message: string;
+};
+export declare function validateResolvedPrimaryDateFieldShape(value: unknown): {
+    ok: true;
+} | {
+    ok: false;
+    issues: ResolvedPrimaryDateFieldIssue[];
+};
+export declare function formatResolvedPrimaryDateFieldIssues(issues: ResolvedPrimaryDateFieldIssue[]): string;

package/dist/types/shared/format-utils/filter-detail.d.ts

@@ -0,0 +1,70 @@
+import { Operator } from '../../lib/types/explorer-types.js';
+import { TemporalBucketMetadata } from '../analytics-protocol/contracts.js';
+import { RelativeDateFilter } from '../analytics-protocol/relative-date-filter.js';
+/**
+ * Filter conditions in full detail, for readers that restate a condition
+ * rather than glance at it (analytics agent Plan 1, D3a-4): the one renderer
+ * for a card's filters and a sheet's inputs alike. Every operator has its
+ * words; literals keep their type; a temporal literal is kept as written and
+ * never read in this machine's time zone; instants that span whole days read
+ * as dates with the zone named; a relative window carries its definition and
+ * a bucketed value its calendar. The compact filter line keeps its own
+ * localized wording. Pure, React-free.
+ */
+/** How a condition's values read. */
+export type FilterLiteralReading = {
+    kind: 'plain';
+} | {
+    kind: 'temporal';
+}
+/** Canonical bucket coordinates in the bucket's governed calendar. */
+ | {
+    kind: 'bucket';
+    bucket: TemporalBucketMetadata;
+};
+export declare const PLAIN_LITERALS: FilterLiteralReading;
+export declare const TEMPORAL_LITERALS: FilterLiteralReading;
+/** What a card's condition and a dashboard filter value both reduce to. */
+export type FullDetailCondition = {
+    /** What the condition is on, as the reader should name it. */
+    subject: string;
+    operator: Operator;
+    values: readonly unknown[];
+    reading: FilterLiteralReading;
+    /** A relative window, authoritative over the bounds it last resolved to. */
+    relative?: RelativeDateFilter;
+    /** Compared with the field's latest value, resolved at run time. */
+    latestValue?: boolean;
+    /** The label a visual showed for the value. */
+    shownAs?: string;
+};
+export type FullDetailOptions = {
+    /** Values listed before "and N more values"; all by default. */
+    maxListedValues?: number;
+    /** Instants spanning whole days in this zone read as those dates. */
+    timeZone?: string;
+};
+export type FilterClauseText = {
+    text: string;
+    /** Values left out of `text` by `maxListedValues`. */
+    omittedValues: number;
+};
+/** One condition in full detail, with the count of values it left out. */
+export declare function describeConditionInFullDetail(condition: FullDetailCondition, options?: FullDetailOptions): FilterClauseText;
+/**
+ * A setting's value (a control's, a SQL parameter's) in full detail: a list
+ * of literals up to the cap, "no value" when unset.
+ */
+export declare function describeSettingValue(value: unknown, options?: Pick<FullDetailOptions, 'maxListedValues'>): FilterClauseText;
+/** One value as a literal: strings quoted, so commas and types stay visible. */
+export declare function formatFilterLiteral(value: unknown, reading?: FilterLiteralReading): string;
+/** Values as literals, at most `max` of them, then "and N more values". */
+export declare function formatFilterLiteralList(values: readonly unknown[], reading?: FilterLiteralReading, max?: number): string;
+/** How many of `count` values a list of at most `max` leaves out. */
+export declare function omittedValueCount(count: number, max?: number): number;
+/**
+ * What a relative window covers, in words that leave nothing to a preset
+ * name: its anchor (now, or the latest date in the data) and whether it keeps
+ * only whole periods.
+ */
+export declare function describeRelativeDateDefinition(relative: RelativeDateFilter): string;

package/dist/types/shared/format-utils/filter-value-text.d.ts

@@ -0,0 +1,15 @@
+import { Operation } from '../../components/surfboard/filter/types.js';
+import { FilterClauseText, FullDetailOptions } from './filter-detail.js';
+/**
+ * A dashboard filter value in full-detail words (analytics agent Plan 1,
+ * D3a-3, D3a-4): through the same renderer as a card's own conditions, so a
+ * sheet input and the same input on a card read alike. Pure, React-free.
+ */
+/** The fields of a dashboard filter value the full-detail text reads. */
+export type FullDetailFilterValue = {
+    operation: Operation;
+    values: readonly unknown[];
+    valueType?: string;
+    relativeMeta?: unknown;
+};
+export declare function describeFilterValueInFullDetail(value: FullDetailFilterValue, subject: string, options?: FullDetailOptions): FilterClauseText;

package/dist/types/shared/format-utils/index.d.ts

@@ -31,6 +31,9 @@ export * from './raw-temporal.js';
 export * from './temporal-input-presentation.js';
 export * from './flat-table-export-totals.js';
 export * from './filter-line.js';
+export { describeFilterValueInFullDetail, type FullDetailFilterValue, } from './filter-value-text.js';
+export { describeConditionInFullDetail, type FilterClauseText } from './filter-detail.js';
+export { formatCanonicalComparisonRange } from '../../lib/utils/comparison-window-caption.js';
 export * from './aggregate-table-row-presentation.js';
 export { PDF_GROUP_CONTINUATION_CLASS } from './grouped-table-presentation.js';
 export { SEMAPHOR_GENERATED_COUNT_METRIC_ID } from '../analytics-protocol/contracts.js';

package/dist/types/shared/format-utils/raw-temporal.d.ts

@@ -64,6 +64,13 @@ export declare function resolveRawTemporalFormat(input: {
     preferences: ResolvedValueFormatPreferences;
     calendar: Pick<CalendarContext, 'tz'>;
 }): ResolvedRawTemporalFormat;
+/**
+ * What a temporal literal is by its text alone: a calendar date, a wall-clock
+ * date-time with no zone, or an instant with a zone or offset. Undefined for
+ * any other text. Readers keep a date and a wall date-time as written; only an
+ * instant names a moment.
+ */
+export declare function classifyTemporalLiteral(value: string): RawTemporalValueKind | undefined;
 export declare function classifyDeclaredSqlTemporalColumn(input: {
     columnKey: string;
     values: readonly (string | null)[];

package/dist/types/shared/format-utils/temporal-bucket.d.ts

@@ -68,6 +68,13 @@ export declare class TemporalBucketContractError extends Error {
     constructor(code: TemporalBucketContractError['code'], message: string);
 }
 export declare function parseTemporalBucketValue(value: TemporalBucketValue, metadata: TemporalBucketMetadata): TemporalBucketValueParseResult;
+/**
+ * A bucket's grain and governed calendar in words, for a reader that restates
+ * a bucketed condition ("by hour in the America/Chicago calendar; each value
+ * is a bucket's start"): the time zone always, the week start for weeks, the
+ * fiscal year start for quarters and years.
+ */
+export declare function describeTemporalBucketCalendar(metadata: TemporalBucketMetadata): string;
 export declare function parseResolvedTemporalBucketFormat(input: unknown): ResolvedTemporalBucketFormatParseResult;
 export declare function resolveTemporalBucketPresentation(input: ResolveTemporalBucketPresentationInput): ResolvedTemporalBucketPresentation;
 export declare function formatTemporalBucket(input: {

package/dist/types/shared/layouts/frame-layouts.d.ts

@@ -0,0 +1,23 @@
+import { Breakpoint, TFrame } from '../../lib/types/common-types.js';
+import { PersistedFrameLayoutItem, PersistedFrameLayouts } from './create-frame-layouts.js';
+export declare function resizeFrameLayoutsForFrameTypeChange({ layouts, previousFrame, nextFrame, }: {
+    layouts: PersistedFrameLayouts | undefined;
+    previousFrame: TFrame | undefined;
+    nextFrame: TFrame;
+}): PersistedFrameLayouts | undefined;
+export declare function addToLayout({ id, layouts, initialHeight, y, x, w, minH, frame, }: {
+    id: string;
+    layouts: PersistedFrameLayouts | undefined;
+    initialHeight?: number;
+    x?: number;
+    y?: number;
+    w?: number;
+    minH?: number;
+    frame?: TFrame;
+}): Partial<Record<Breakpoint, PersistedFrameLayoutItem[]>>;
+export declare function removeFromLayout(id: string, layouts: PersistedFrameLayouts | undefined): PersistedFrameLayouts | undefined;
+export declare function duplicateLayoutItem({ sourceId, duplicatedId, layouts, }: {
+    sourceId: string;
+    duplicatedId: string;
+    layouts: PersistedFrameLayouts | undefined;
+}): PersistedFrameLayouts | undefined;

package/dist/types/shared/layouts/index.d.ts

@@ -1 +1,2 @@
 export * from './create-frame-layouts.js';
+export * from './frame-layouts.js';

package/package.json

@@ -5,7 +5,7 @@
     "email": "support@semaphor.cloud"
   },
   "license": "MIT",
-  "version": "0.1.537",
+  "version": "0.1.539",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",
@@ -56,6 +56,14 @@
       "types": "./dist/types/analytics-protocol.d.ts",
       "import": "./dist/analytics-protocol/index.js"
     },
+    "./assistant-protocol": {
+      "types": "./dist/types/assistant-protocol.d.ts",
+      "import": "./dist/assistant-protocol/index.js"
+    },
+    "./assistant-context": {
+      "types": "./dist/types/assistant-context.d.ts",
+      "import": "./dist/assistant-context/index.js"
+    },
     "./data-app-sdk": {
       "types": "./dist/types/data-app-sdk.d.ts",
       "import": "./dist/data-app-sdk/index.js"
@@ -111,7 +119,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",
+    "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",
     "preview": "vite preview",
     "test": "vitest run",
     "test:changed": "vitest run --changed",
@@ -140,6 +148,7 @@
     "link:restore": "./scripts/link-helper.sh restore"
   },
   "dependencies": {
+    "@ai-sdk/react": "^4.0.140",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
@@ -179,6 +188,7 @@
     "@tanstack/react-query": "^5.62.15",
     "@tanstack/react-table": "^8.11.7",
     "@tanstack/react-virtual": "^3.13.26",
+    "ai": "^7.0.137",
     "chart.js": "^4.4.1",
     "chartjs-chart-funnel": "^4.2.4",
     "chartjs-chart-geo": "^4.3.4",