react-semaphor 0.1.533 → 0.1.534

package/dist/types/shared/analytics-protocol/sort-target.d.ts

@@ -0,0 +1,40 @@
+import { MetricResultAliasInput } from './metric-comparison.js';
+export type SortTargetField = MetricResultAliasInput & {
+    readonly id?: string;
+};
+export type SortTargetRole = 'metric' | 'groupby' | 'detail';
+/** One kind of column in the query, in the order sorts search them. */
+export type SortTargetGroup = {
+    readonly role: SortTargetRole;
+    readonly fields: readonly SortTargetField[];
+};
+export type SortTargetRef = {
+    readonly id?: string;
+    readonly name: string;
+    readonly entityName?: string;
+    readonly alias?: string;
+};
+export type SortTarget = {
+    readonly group: number;
+    readonly index: number;
+};
+/**
+ * The result alias that identifies one column instance: its own alias, else
+ * the generated one (for a metric, with its aggregate). A sort entry carries
+ * it as `alias` to name exactly that column.
+ */
+export declare function sortTargetAlias(field: SortTargetField, role: SortTargetRole): string;
+/**
+ * The column a sort entry names, searched across the query's column groups in
+ * order (for a grouped query: metrics, then group columns). A column instance
+ * is its id plus its result alias: SUM and AVG of one field can share an id,
+ * and so can a group column and a count of it. In order:
+ * 1. the column with the entry's id whose result alias is the entry's alias;
+ * 2. the only column with the entry's id;
+ * 3. group by group, the first column with the entry's name and entity whose
+ *    alias is the entry's, or any alias when the entry has none (the rule
+ *    before sort entries carried ids).
+ * The query builder and the browser resolve sorts only here, so the sort a
+ * viewer sees is the sort the query runs.
+ */
+export declare function findSortTarget(groups: readonly SortTargetGroup[], sort: SortTargetRef): SortTarget | undefined;

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

@@ -6,4 +6,13 @@ declare const OPERATIONS_BY_DATA_TYPE: {
 };
 export declare function dashboardFilterValueTypeForDataType(dataType: unknown): keyof typeof OPERATIONS_BY_DATA_TYPE;
 export declare function isDashboardFilterOperationCompatible(dataType: unknown, operation: unknown): boolean;
+/** Every filter operation a stored filter value may name. */
+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.
+ */
+export declare function validateDashboardFilterValues(operation: unknown, values: readonly unknown[], valueType: DashboardFilterScalarType | undefined, location: string, errors: string[]): void;
 export {};

package/dist/types/shared/dashboard-viewer/bookmark-state.d.ts

@@ -0,0 +1,35 @@
+import { ParseResult } from './table-settings.js';
+import { BookmarkState } from './viewer-contract.js';
+/** A part of a stored bookmark that could not be read; it is left out. */
+export type BookmarkStateIssue = {
+    readonly target: 'input' | 'selection' | 'sheet' | 'card';
+    /**
+     * The input id (a click selection's for `selection`), sheet id or card id;
+     * for a malformed input section, its path (`shared`, `byCardId.<id>`).
+     */
+    readonly id: string;
+};
+export type BookmarkStateRead = {
+    readonly ok: true;
+    readonly value: BookmarkState;
+    /** Parts left out because they could not be read. */
+    readonly issues: readonly BookmarkStateIssue[];
+    /** Keys this version does not define (ignored on read, rejected on write). */
+    readonly unknownKeys: readonly string[];
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Reads a stored bookmark, keeping every part that parses: a slot, sheet or
+ * table entry that doesn't is left out and reported in `issues`, so one bad
+ * entry never costs the rest of the bookmark. Fails only for another version
+ * or a state that is not an object. Reconciliation against the dashboard
+ * (removed inputs, sheets or cards) happens when it is applied, not here.
+ */
+export declare function readBookmarkState(json: unknown, version: number): BookmarkStateRead;
+/**
+ * The write check: the bookmark must read completely, with no part left out
+ * and no unknown key. Empty table entries are dropped.
+ */
+export declare function parseBookmarkState(json: unknown, version: number): ParseResult<BookmarkState>;

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

@@ -0,0 +1,3 @@
+export * from './bookmark-state.js';
+export * from './table-settings.js';
+export * from './viewer-contract.js';

package/dist/types/shared/dashboard-viewer/table-settings.d.ts

@@ -0,0 +1,89 @@
+import { TCard, TDashboard } from '../../lib/types/common-types.js';
+export declare const VIEWER_LIMITS: {
+    readonly bookmarksPerViewerPerDashboard: 20;
+    readonly bookmarkNameMaxChars: 100;
+    readonly columnLabelMaxChars: 120;
+    readonly tableSettingsMaxBytes: 65536;
+    readonly rememberedTableSettingsMaxBytes: 262144;
+    readonly bookmarkStateMaxBytes: 65536;
+};
+export declare const VIEWER_TABLE_SETTINGS_VERSION: 1;
+export type ParseResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/** UTF-8 bytes of `JSON.stringify(value)`: the browser-side size measure. */
+export declare function measureJsonBytes(value: unknown): number;
+export type TableColumnIdentity = {
+    readonly kind: 'dimension';
+    readonly role: 'detail' | 'groupby';
+    readonly fieldId: string;
+} | {
+    readonly kind: 'metric';
+    readonly metricId: string;
+    readonly metricAlias: string;
+} | {
+    readonly kind: 'result';
+    readonly key: string;
+};
+/**
+ * Serialized column identity: "dim:<role>:<fieldId>" | "metric:<metricId>:<metricAlias>"
+ * | "result:<key>", each segment percent-encoded. Branded so an output key can't
+ * be passed where a column id is expected.
+ */
+export type TableColumnId = string & {
+    readonly __brand: 'TableColumnId';
+};
+export declare function toTableColumnId(identity: TableColumnIdentity): TableColumnId;
+/** `undefined` for a malformed or non-canonical id; settings parsers drop those. */
+export declare function parseTableColumnId(value: string): TableColumnIdentity | undefined;
+export type TableSortEntry = {
+    readonly columnId: TableColumnId;
+    readonly direction: 'asc' | 'desc';
+};
+/**
+ * One viewer's choices for one table card. Sparse and normalized: a field that
+ * is empty or equals the author's is omitted, and settings equal to the
+ * author's table are `undefined`, never `{}`.
+ */
+export type ViewerTableSettings = {
+    /** Arrangement of addressable columns. Unlisted columns keep their author-relative position. */
+    readonly order?: readonly TableColumnId[];
+    readonly hidden?: readonly TableColumnId[];
+    /** Display names. Downloads use them too. */
+    readonly labels?: Readonly<Record<TableColumnId, string>>;
+    /** Absent: the author's sort. `[]`: explicitly unsorted. Never saved in `page-only` mode. */
+    readonly sort?: readonly TableSortEntry[];
+};
+/**
+ * Drops empty fields and duplicate or malformed column ids. `sort: []` is kept:
+ * it means "explicitly unsorted". Returns `undefined` when nothing is left.
+ */
+export declare function normalizeViewerTableSettings(settings: ViewerTableSettings | undefined): ViewerTableSettings | undefined;
+export declare function isEmptyViewerTableSettings(settings: ViewerTableSettings | undefined): boolean;
+/**
+ * Strict shape check, then normalization: malformed column ids are dropped,
+ * a structural problem (unknown key, wrong type, a name over 120 characters) is
+ * an error. An empty result parses to `{}`; callers treat it as "no settings".
+ */
+export declare function parseViewerTableSettings(json: unknown, version: number): ParseResult<ViewerTableSettings>;
+/** Parses a `Record<cardId, ViewerTableSettings>`, keeping only `cardIds` and dropping entries that fail. */
+export declare function parseViewerTableSettingsMap(json: unknown, version: number, cardIds: ReadonlySet<string>): Readonly<Record<string, ViewerTableSettings>>;
+/**
+ * True for a `table` or `detailTable` card: a viewer can sort it. With
+ * customization off the sort lasts for the visit and is never saved (PLAN B30).
+ */
+export declare function isTableCardSortable(card: Pick<TCard, 'type'>): boolean;
+/**
+ * True for a `table` or `detailTable` card whose author left customization on
+ * (absent = on): a viewer can hide, reorder and rename its columns, and their
+ * settings are remembered and saved in bookmarks.
+ */
+export declare function isTableCardCustomizable(card: Pick<TCard, 'type' | 'preferences'>): boolean;
+/** Dashboard `table`/`detailTable` cards (not document sections): every table a viewer can sort. */
+export declare function getSortableTableCardIds(dashboard: Pick<TDashboard, 'sheets'>): ReadonlySet<string>;
+/** Dashboard `table`/`detailTable` cards (not document sections) whose author left `allowViewerColumnCustomization` on. */
+export declare function getCustomizableTableCardIds(dashboard: Pick<TDashboard, 'sheets'>): ReadonlySet<string>;

package/dist/types/shared/dashboard-viewer/viewer-contract.d.ts

@@ -0,0 +1,95 @@
+import { DashboardInputValues } from '../../lib/types/common-types.js';
+import { ViewerTableSettings } from './table-settings.js';
+export declare const BOOKMARK_STATE_VERSION: 1;
+/** What a bookmark stores: only the differences from the baseline. */
+export type BookmarkState = {
+    readonly version: 1;
+    /** Omitted when it is the author's first sheet. */
+    readonly selectedSheetId?: string;
+    /** Differing slots only. `{ status: 'cleared' }` = the viewer removed a default. */
+    readonly inputs?: DashboardInputValues;
+    /** Customized cards only, keyed by card id. */
+    readonly tableSettings?: Readonly<Record<string, ViewerTableSettings>>;
+};
+/**
+ * Who can open a bookmark. `TEAM`: the owner's tenant (tenant users) or
+ * organization (org users). `DASHBOARD`: everyone who can open the dashboard;
+ * created by org users who can edit it. A shared bookmark carries its values
+ * as saved; every query runs under the reader's own access (PLAN B31).
+ */
+export declare const BOOKMARK_VISIBILITIES: readonly ["PRIVATE", "TEAM", "DASHBOARD"];
+export type BookmarkVisibility = (typeof BOOKMARK_VISIBILITIES)[number];
+export type Bookmark = {
+    readonly id: string;
+    readonly name: string;
+    readonly revision: number;
+    readonly state: BookmarkState;
+    readonly visibility: BookmarkVisibility;
+    /** Only the owner updates, renames, deletes or changes visibility. */
+    readonly isOwn: boolean;
+    /** The owner's display name, for bookmarks shared by someone else. */
+    readonly ownerName?: string;
+};
+export type BookmarkSummary = {
+    readonly id: string;
+    readonly name: string;
+    readonly revision: number;
+    readonly isDefault: boolean;
+    /** ISO 8601. */
+    readonly updatedAt: string;
+    readonly visibility: BookmarkVisibility;
+    readonly isOwn: boolean;
+    readonly ownerName?: string;
+};
+export type ViewerAccessMode = 'read-write' | 'read-only' | 'session-only';
+export type ViewerAccessReason = 
+/** read-only */
+'impersonating'
+/** session-only: the token names no person (tenant-only or no identity). */
+ | 'no-viewer-identity'
+/** session-only: the token names a tenant user who does not exist. */
+ | 'user-not-provisioned';
+/** `GetDashboardResponse.viewer`. Absent when `openViewerState` fails; the client then acts as session-only. */
+export type DashboardViewerPayload = {
+    readonly access: ViewerAccessMode;
+    readonly accessReason?: ViewerAccessReason;
+    /** Remembered settings, filtered to customizable cards and parsed. `{}` for session-only. */
+    readonly tableSettings: Readonly<Record<string, ViewerTableSettings>>;
+    /** Phase 2. Present only if it exists, is on this dashboard and is visible to the viewer now. */
+    readonly defaultBookmark?: Bookmark;
+    /** Phase 3. Present when the viewer has saved state: who `TEAM` means, and whether they can publish dashboard views. */
+    readonly sharing?: {
+        /** Who "My team" reaches; absent when the viewer has no team (an org user outside any organization). */
+        readonly teamScope?: 'tenant' | 'organization';
+        readonly canPublish: boolean;
+    };
+};
+/**
+ * How many saved bookmarks and remembered table settings reference each part
+ * of a dashboard: counts only, never names or values. Editors only; feeds the
+ * author impact warning (`describeBookmarkImpact`).
+ */
+export type BookmarkUsage = {
+    readonly bookmarks: number;
+    /** Bookmarks with a slot for the input, in any scope. */
+    readonly inputs: Readonly<Record<string, number>>;
+    /** Bookmarks that open on the sheet or keep values for it. */
+    readonly sheets: Readonly<Record<string, number>>;
+    readonly tables: Readonly<Record<string, {
+        readonly bookmarks: number;
+        /** Viewers with remembered settings for the table. */
+        readonly remembered: number;
+        /** Per column: bookmarks and remembered settings that name it. */
+        readonly columns: Readonly<Record<string, {
+            readonly bookmarks: number;
+            readonly remembered: number;
+        }>>;
+    }>>;
+};
+export type ViewerErrorCode = 'not-found' | 'forbidden' | 'read-only' | 'invalid' | 'not-eligible' | 'too-large' | 'limit-reached' | 'revision-conflict';
+export type ViewerErrorBody = {
+    readonly error: string;
+    readonly code: ViewerErrorCode;
+    /** With `revision-conflict`. */
+    readonly currentRevision?: number;
+};

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

@@ -0,0 +1,47 @@
+import { RelativeDateFilter } from '../analytics-protocol/index.js';
+/**
+ * The fields of a filter value the filter line reads. A dashboard filter
+ * value fits it; the server builds a run's line from the same saved values.
+ */
+export type FilterLineValue = {
+    name: string;
+    operation: string;
+    values: readonly unknown[];
+    valueType?: string;
+    temporalPrecision?: string;
+    relativeMeta?: unknown;
+};
+type FormatFilterLineOptions = {
+    timezone?: string;
+};
+type FormatFilterConditionOptions = FormatFilterLineOptions & {
+    /** The filter's display name; defaults to its column name in title case. */
+    label?: string;
+};
+/**
+ * The filter line heads a PDF and travels in export requests, so a long
+ * multi-select is summarized rather than listed in full.
+ */
+export declare const FILTER_LINE_MAX_LISTED_VALUES = 10;
+/**
+ * The relative window a filter line prints by name instead of dates, with its
+ * range operator kept ("Closed On: This year", "Created At not in Last 30
+ * days of data"). Two kinds: a window counted from the latest data, which has
+ * no bounds until a query finds that data (analytics kernel K12), and a
+ * window in quarters or years, whose bounds follow the fiscal year of each
+ * card's data model, so one set of dates could be wrong for some cards. Any
+ * other relative window prints the dates it resolves to.
+ */
+export declare function readNamedRelativeWindow(filter: FilterLineValue): RelativeDateFilter | undefined;
+/**
+ * One filter value as a readable condition, operator included: "Region not in
+ * (West)", "Amount ≥ 100". Empty for a non-null operation with no values.
+ */
+export declare function formatFilterCondition(filter: FilterLineValue, options?: FormatFilterConditionOptions): string;
+/**
+ * Converts an array of filter values into a human-readable filter line
+ * @param filterValues Filter values (dashboard filter values fit)
+ * @returns Human-readable filter description string
+ */
+export declare function formatFilterLine(filterValues: readonly FilterLineValue[], options?: FormatFilterLineOptions): string;
+export {};

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

@@ -30,6 +30,7 @@ export * from './temporal-bucket.js';
 export * from './raw-temporal.js';
 export * from './temporal-input-presentation.js';
 export * from './flat-table-export-totals.js';
+export * from './filter-line.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/package.json

@@ -5,7 +5,7 @@
     "email": "support@semaphor.cloud"
   },
   "license": "MIT",
-  "version": "0.1.533",
+  "version": "0.1.534",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",
@@ -115,7 +115,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",
+    "check:guards": "node scripts/card-config-consumers.mjs && node scripts/components-entry-imports.mjs && node scripts/types-entry-imports.mjs",
     "preview": "vite preview",
     "test": "vitest run",
     "test:changed": "vitest run --changed",