react-semaphor 0.1.532 → 0.1.534

package/dist/surfboard/index.js

@@ -1,5 +1,5 @@
-import { a, R as s, D as o } from "../chunks/report-preferences-dialog-Cv_2GMlz.js";
-import { C as f, E as D } from "../chunks/common-types-C6cAQgyh.js";
+import { a, R as s, D as o } from "../chunks/report-preferences-dialog-CWdTlWsr.js";
+import { C as f, E as D } from "../chunks/common-types-g7yS12Cg.js";
 export {
   f as CONTROL_CARD_DEFAULT_VALUE,
   a as DisplayFormatPreferencesFields,

package/dist/types/briefings/index.d.ts

@@ -192,7 +192,6 @@ export type BriefingAttachmentSettings = {
     filterValues?: unknown[];
     inlineFilterValues?: unknown[];
     sheetFilterValues?: unknown[];
-    filterLine?: string;
     controlValues?: Record<string, unknown>;
     controlDefinitions?: unknown[];
     cardControlDefinitions?: unknown[];

package/dist/types/components/surfboard/filter/types.d.ts

@@ -15,6 +15,15 @@ export type ComboBoxOption = {
 export type TSelectedRecord = ComboBoxOption;
 export type { DateUnit, RelativeDateFilter, RelativeDateUnit, SubDayDateUnit, };
 export type TemporalPrecision = 'minute';
+/**
+ * Options for a relative date pick ("Today", "Last 7 days"). The pick is a
+ * window; `operation` is the range condition it runs under: "between" keeps
+ * the window, "not between" excludes it. Absent means "between".
+ */
+export type RelativeDateChangeOptions = {
+    temporalPrecision?: TemporalPrecision;
+    operation?: 'between' | 'not between';
+};
 /**
  * Absolute fixed month/year default used by Month Picker defaults.
  * - `month` is 0-indexed (0=January, 11=December) to align with MonthPicker.

package/dist/types/components/ui-custom/date-range-presets.d.ts

@@ -1,5 +1,9 @@
 import { DefaultDateFilter, FixedDayDefaultDateFilter, FixedMonthDefaultDateFilter, RelativeDateFilter } from '../surfboard/filter/types.js';
 import { WeekStart } from '../../lib/types/token-types.js';
+import { CalendarContext } from '../../shared/report-runtime-context/index.js';
+/** Calendar inputs for defaults, including reproducible and fiscal reports. */
+export type DefaultDateCalendar = Pick<CalendarContext, 'tz' | 'weekStart'> & Partial<Pick<CalendarContext, 'anchor' | 'fiscalCalendar'>>;
+/** A valid relative date, read by the shared protocol reader. */
 export declare const isRelativeDateFilter: (value: unknown) => value is RelativeDateFilter;
 export declare const isFixedMonthDefaultDateFilter: (value: unknown) => value is FixedMonthDefaultDateFilter;
 export declare const isFixedDayDefaultDateFilter: (value: unknown) => value is FixedDayDefaultDateFilter;
@@ -17,7 +21,7 @@ export declare function resolveCalendarDayRange(date: string, timezone: string):
  * silently widening the filter.
  */
 export declare const isSingleDayDefaultDateFilter: (value: DefaultDateFilter | undefined) => boolean;
-export declare function resolveDefaultDateFilterForDefaults(meta: DefaultDateFilter, timezone: string, weekStart?: WeekStart): [Date, Date] | undefined;
+export declare function resolveDefaultDateFilterForDefaults(meta: DefaultDateFilter, calendar: string | DefaultDateCalendar, weekStart?: WeekStart): [Date, Date] | undefined;
 /**
  * The window a relative date names at `now` in the timezone, from the shared
  * date module (analytics kernel Phase 3), so a preview matches what the server

package/dist/types/components/visual/data-table/hooks/use-data-table-logic.d.ts

@@ -7,6 +7,13 @@ import { RawTemporalValueKind, SemaphorResultColumn } from '../../../../shared/a
 import { ConditionalFormattingRenderContext, TableBaseFormatting, TableBaseStyle } from '../../../../lib/table-formatting/index.js';
 import { ColumnReorderRequest } from '../../shared/utils/table-column-order.js';
 import { RawTemporalPresentation } from '../../../../lib/formatters/raw-temporal-presentation.js';
+import { ViewerDataTable } from '../../../../lib/dashboard-viewer/use-table-view.js';
+/**
+ * A dashboard table seen by a viewer (dashboard bookmarks): the viewer's table
+ * settings shape the columns and the sort is controlled by them. Absent in the
+ * editor and while the dashboard is edited.
+ */
+export type DataTableViewerContext = ViewerDataTable;
 interface DataTableLogicProps {
     data: any[];
     resultColumns?: SemaphorResultColumn[];
@@ -43,6 +50,7 @@ interface DataTableLogicProps {
     headerTextClassName?: string;
     headerWrapText?: boolean;
     appearanceWrapText?: boolean;
+    viewerTable?: DataTableViewerContext;
 }
 export declare function useDataTableLogic(props: DataTableLogicProps): {
     table: import('@tanstack/table-core').Table<any>;

package/dist/types/components/visual/data-table/types/data-table.d.ts

@@ -118,6 +118,12 @@ export type TablePreferences = {
     forceClientPagination?: boolean;
     density?: TableDensity;
     tableStyle?: TableStylePreferences;
+    /**
+     * Viewers may hide, reorder and rename this table's columns for themselves,
+     * and their column changes are remembered. Absent means on; only `false`
+     * turns it off. Viewers sort either way (PLAN B30).
+     */
+    allowViewerColumnCustomization?: boolean;
 };
 export type PersistedColumnSettings = Omit<Partial<ColumnSettings>, 'numberFormat' | 'dateFormat'> & {
     numberFormat?: Partial<ColumnSettings['numberFormat']>;
@@ -174,6 +180,11 @@ export interface DataTableProps {
     onUpdateAllColumnVisibility?: (visibility: Record<string, boolean>) => void;
     sortState?: SortingState;
     onSortChange?: (sorting: SortingState) => void;
+    /**
+     * Set when a viewer looks at a dashboard table (dashboard bookmarks): their
+     * table settings shape the columns and control the sort.
+     */
+    viewerTable?: import('../hooks/use-data-table-logic.js').DataTableViewerContext;
     onColumnReorder?: (request: ColumnReorderRequest) => boolean;
     paginationMetadata?: PaginationMetadata;
     onPaginationChange?: (pageIndex: number, pageSize: number) => void;

package/dist/types/components/visual/shared/utils/table-column-order.d.ts

@@ -23,12 +23,27 @@ export declare function resolveDataTableColumnDisplayLabel(columnId: string, car
 export declare function buildDataTableColumnDisplayLabels(columnIds: readonly string[], card: TCard | undefined, columnKeyMap?: QueryColumnKeyMap, resultColumns?: readonly SemaphorResultColumn[], temporalPresentation?: GroupedTemporalPresentation): {
     [k: string]: string;
 };
+export declare function resolveExactRegularTablePivotColumn(input: {
+    resultColumn: SemaphorResultColumn | undefined;
+    card: TCard & {
+        config: CardConfig;
+    };
+    columnKeyMap?: QueryColumnKeyMap;
+}): {
+    resultColumn: SemaphorResultColumn;
+    identity: import('../../../../shared/analytics-protocol/index.js').SemaphorPivotResultColumnIdentity;
+    pivotFields: import('../../../../lib/types/explorer-types.js').PivotByField[];
+    authoredMetrics: MetricField[];
+    authoredMetric: MetricField | undefined;
+} | undefined;
 export declare function resolvePivotColumnDisplayLabel(input: {
     columnId: string;
     card: TCard | undefined;
     columnKeyMap?: QueryColumnKeyMap;
     resultColumns?: readonly SemaphorResultColumn[];
     temporalPresentation?: GroupedTemporalPresentation;
+    /** A viewer's name for the metric; replaces the metric part of the header. */
+    metricLabelOverride?: string;
 }): string | undefined;
 export declare function resolveMetricSchemaDisplayLabel(schema: PivotColumnSchema | undefined, card: TCard | undefined, columnKeyMap?: QueryColumnKeyMap, fallback?: string): string;
 export declare function orderDataTableKeysByCardConfig(keys: string[], card: TCard | undefined, getComparisonKey?: (metricLabel: string) => string | null, columnKeyMap?: QueryColumnKeyMap): string[];

package/dist/types/index.js

@@ -1,9 +1,10 @@
-import { C as r, E as s } from "../chunks/common-types-C6cAQgyh.js";
-import { C as o, D as i, L as n, P as c, f as d, g as m, k as u, j as E, l as p, e as C, c as D, b as F, d as A, n as f, h as _ } from "../chunks/validators-BS521dum.js";
-import { c as T, g as h, f as x, b as N, e as y, d as I, a as M, h as R, r as b } from "../chunks/field-dependencies-BWStuMxe.js";
-import { D as S } from "../chunks/token-types-Brc30mNN.js";
-import { r as O, a as v } from "../chunks/pivot-result-identity-BhAm8MCg.js";
-import { D as w } from "../chunks/report-runtime-context-DceiWMKz.js";
+import { C as s, E as r } from "../chunks/common-types-g7yS12Cg.js";
+import { C as o, D as i, L as n, P as d, f as m, g as u, k as c, j as E, l as p, e as C, c as T, b as D, d as A, n as I, h as _ } from "../chunks/validators-DMSH81OM.js";
+import { c as S, g as b, f, b as L, e as N, d as R, a as g, h, r as x } from "../chunks/field-dependencies-CpRUwr9J.js";
+import { D as M } from "../chunks/token-types-DtSJOUjh.js";
+import { B as V, j as k, V as w, a as U, h as B, g as K, i as z, f as v, e as P, m as Y, n as G, p as Q, b as j, c as q, d as W, r as J, t as X } from "../chunks/bookmark-state-B-I9BDD0.js";
+import { r as Z, a as $ } from "../chunks/pivot-result-identity-Bs4tLtLo.js";
+import { D as ae } from "../chunks/report-runtime-context-CG_I0PPW.js";
 const e = [
   "concatenate",
   "conditional-category",
@@ -37,35 +38,52 @@ const e = [
   "is-blank"
 ];
 export {
+  V as BOOKMARK_STATE_VERSION,
+  k as BOOKMARK_VISIBILITIES,
   o as CALCULATED_FIELD_ENTITY_MARKER,
   e as CALCULATED_FIELD_TEMPLATE_IDS,
-  r as CONTROL_CARD_DEFAULT_VALUE,
+  s as CONTROL_CARD_DEFAULT_VALUE,
   i as DATE_FORMAT_VALUES,
-  w as DEFAULT_CALENDAR_CONTEXT,
-  S as DEFAULT_SEMANTIC_DOMAIN_ACCESS,
-  s as EMPTY_SELECTION,
+  ae as DEFAULT_CALENDAR_CONTEXT,
+  M as DEFAULT_SEMANTIC_DOMAIN_ACCESS,
+  r as EMPTY_SELECTION,
   n as LEGACY_CALCULATED_FIELD_ENTITY_MARKER,
-  c as PivotMarkerEnum,
-  T as collectDatasetNamesFromExplorerField,
-  h as collectDatasetNamesFromFilterGroup,
-  x as collectExecutionDatasetNamesFromExplorerField,
-  N as collectPreferredDatasetNamesFromExplorerField,
-  y as collectQualifiedDatasetNamesFromExplorerField,
-  I as datasetRefFromSource,
-  M as dependencyDisplayIdentity,
-  d as getCalculatedFieldComputeStage,
-  m as getFieldRuntimeColumnName,
-  u as hasCalculatedFieldMarker,
+  d as PivotMarkerEnum,
+  w as VIEWER_LIMITS,
+  U as VIEWER_TABLE_SETTINGS_VERSION,
+  S as collectDatasetNamesFromExplorerField,
+  b as collectDatasetNamesFromFilterGroup,
+  f as collectExecutionDatasetNamesFromExplorerField,
+  L as collectPreferredDatasetNamesFromExplorerField,
+  N as collectQualifiedDatasetNamesFromExplorerField,
+  R as datasetRefFromSource,
+  g as dependencyDisplayIdentity,
+  m as getCalculatedFieldComputeStage,
+  B as getCustomizableTableCardIds,
+  u as getFieldRuntimeColumnName,
+  K as getSortableTableCardIds,
+  c as hasCalculatedFieldMarker,
   E as hasCalculatedFormulaInputs,
   p as hasSyntheticCalculatedFieldOwner,
-  R as humanizeDatasetName,
+  h as humanizeDatasetName,
   C as inspectCalculatedField,
-  D as isCalculatedDimension,
-  F as isCalculatedMetric,
+  T as isCalculatedDimension,
+  D as isCalculatedMetric,
   A as isDerivedField,
-  f as normalizeCalculatedFieldRepresentation,
-  b as resolveFieldDatasetDependencies,
-  O as resolveQueryColumnKeyMapEntry,
-  v as resolveUniqueQueryColumnKeyMapEntry,
-  _ as shouldDropInheritedCalculationAggregate
+  z as isEmptyViewerTableSettings,
+  v as isTableCardCustomizable,
+  P as isTableCardSortable,
+  Y as measureJsonBytes,
+  I as normalizeCalculatedFieldRepresentation,
+  G as normalizeViewerTableSettings,
+  Q as parseBookmarkState,
+  j as parseTableColumnId,
+  q as parseViewerTableSettings,
+  W as parseViewerTableSettingsMap,
+  J as readBookmarkState,
+  x as resolveFieldDatasetDependencies,
+  Z as resolveQueryColumnKeyMapEntry,
+  $ as resolveUniqueQueryColumnKeyMapEntry,
+  _ as shouldDropInheritedCalculationAggregate,
+  X as toTableColumnId
 };

package/dist/types/lib/api/exports-api.d.ts

@@ -83,7 +83,12 @@ export interface ExportJobStatus {
     createdAt: string;
     completedAt?: string;
     expiresAt: string;
+    /** Matrix exports: where the export is (the server computes it from committed work). */
+    phase?: MatrixExportPhase;
+    /** When the server stops the export (ISO); the browser gives up a grace period later. */
+    deadlineAt?: string;
 }
+export type MatrixExportPhase = 'preparing' | 'acquiring' | 'finalizing' | 'completed';
 /** Export job from list endpoint */
 export interface ExportJobListItem {
     progress?: number | null;
@@ -102,6 +107,8 @@ export interface ExportJobListItem {
     expiresAt: string;
     dashboardId?: string;
     cardId?: string;
+    phase?: MatrixExportPhase;
+    deadlineAt?: string;
 }
 /** API error response */
 export interface ExportApiError {
@@ -113,25 +120,45 @@ export interface ExportApiError {
  * Create a new export job
  */
 export declare function createExport(apiServiceUrl: string, token: string, params: CardExportRequest): Promise<CreateExportResponse>;
+/** The direct path's answer (MX-D11): the file, or the background export it started. */
+export type MatrixDirectExportResult = {
+    kind: 'file';
+    file: Blob;
+    fileName: string;
+} | {
+    kind: 'background';
+    exportId: string;
+    status: 'pending' | 'processing';
+    deadlineAt: string | null;
+};
+/**
+ * A Matrix CSV a user downloads: built in the request when it fits the direct
+ * limits, otherwise moved to a background export by the server. The file is
+ * read as bytes, so its BOM survives. Errors carry the server's catalog
+ * reason in `details.message`.
+ */
+export declare function createMatrixDirectExport(apiServiceUrl: string, token: string, params: MatrixCsvExportRequest & {
+    format: 'csv';
+}): Promise<MatrixDirectExportResult>;
 /**
  * Get list of user's exports
  */
 export declare function getExports(apiServiceUrl: string, token: string, options?: {
     status?: ExportStatus[];
     limit?: number;
-}): Promise<{
+}, signal?: AbortSignal): Promise<{
     exports: ExportJobListItem[];
 }>;
 /**
  * Get status of a specific export job
  */
-export declare function getExportStatus(apiServiceUrl: string, token: string, exportId: string): Promise<ExportJobStatus>;
+export declare function getExportStatus(apiServiceUrl: string, token: string, exportId: string, signal?: AbortSignal): Promise<ExportJobStatus>;
 /**
  * Get download URL for a completed export
  *
  * The backend returns a presigned S3 URL in JSON response.
  */
-export declare function getDownloadUrl(apiServiceUrl: string, token: string, exportId: string): Promise<string>;
+export declare function getDownloadUrl(apiServiceUrl: string, token: string, exportId: string, signal?: AbortSignal): Promise<string>;
 /**
  * Cancel/delete an export job
  */

package/dist/types/lib/dashboard-viewer/export-table-view.d.ts

@@ -0,0 +1,43 @@
+import { TCard, TDashboard } from '../types/common-types.js';
+import { TablePreferences } from '../../components/visual/data-table/types/data-table.js';
+import { QueryColumnKeyMap } from '../types/explorer-types.js';
+import { ComparisonMetadataMap } from '../types/query-types.js';
+import { SemaphorResultColumn } from '../../shared/analytics-protocol/index.js';
+import { TableView } from './table-view.js';
+import { ViewerTableSettings } from '../../shared/dashboard-viewer/index.js';
+import { DashboardViewerState } from './viewer-store-state.js';
+/**
+ * The viewer's table settings captured at the download click (PLAN B20): a
+ * download uses these, never saved preferences read later.
+ */
+export type ExportViewerTable = {
+    readonly settings?: ViewerTableSettings;
+};
+/**
+ * The viewer's table for one card, read from the store when the viewer clicks
+ * a download, and passed unchanged through every step and fallback after it.
+ * Every download mount goes through here, so none can forget the viewer's
+ * columns (PLAN B26). `undefined` where the authored table applies: the
+ * dashboard or a visual is being edited, or the card is not on the dashboard.
+ */
+export declare function readExportViewerTable(state: {
+    readonly dashboard: TDashboard;
+    readonly viewer: DashboardViewerState;
+    readonly isDashboardEditing: boolean;
+}, cardId: string, options: {
+    readonly isEditorPreview: boolean;
+}): ExportViewerTable | undefined;
+/**
+ * The columns a download writes: `resolveTableView` in its `export`
+ * projection over the result being downloaded (TECH-SPEC 9).
+ */
+export declare function resolveExportTableView(input: {
+    readonly card: TCard;
+    readonly records: readonly Record<string, unknown>[];
+    readonly columnKeyMap?: QueryColumnKeyMap;
+    readonly resultColumns?: readonly SemaphorResultColumn[];
+    readonly comparisonMetadata?: ComparisonMetadataMap;
+    readonly viewerTable?: ExportViewerTable;
+}): TableView;
+/** The card with the author's table preferences an export was given (they decide what the author hid). */
+export declare function withTablePreferences(card: TCard, tablePreferences: TablePreferences | undefined): TCard;

package/dist/types/lib/dashboard-viewer/table-view-edit.d.ts

@@ -0,0 +1,14 @@
+import { ViewerTableSettings } from '../../shared/dashboard-viewer/table-settings.js';
+import { TableColumnEdit, TableView } from './table-view.js';
+export type TableColumnEditResult = {
+    readonly settings: ViewerTableSettings | undefined;
+    /** `too-large`: the edit would push this card's settings past 64 KiB, so it was not applied. */
+    readonly status: 'applied' | 'unchanged' | 'too-large';
+};
+/**
+ * Applies one column edit (section 5.4) and returns normalized settings
+ * (`undefined` = the author's table) with the outcome, for the store and the
+ * column panel. `stored` is the card's settings before reconciliation: entries
+ * for columns this result does not show (a drill can hide them) are kept.
+ */
+export declare function computeTableColumnEdit(view: TableView, edit: TableColumnEdit, stored?: ViewerTableSettings | undefined): TableColumnEditResult;

package/dist/types/lib/dashboard-viewer/table-view.d.ts

@@ -0,0 +1,150 @@
+import { TCard } from '../types/common-types.js';
+import { CardConfig, DetailField, GroupByField, MetricField, QueryColumnKeyMap } from '../types/explorer-types.js';
+import { ComparisonMetadataMap } from '../types/query-types.js';
+import { SemaphorResultColumn } from '../../shared/analytics-protocol/index.js';
+import { TableColumnId, ViewerTableSettings } from '../../shared/dashboard-viewer/table-settings.js';
+export type TableResultShape = {
+    /** Output keys present in the result rows, in transport order. */
+    readonly keys: readonly string[];
+    /** The rows the keys came from; only the generated-count check reads them. */
+    readonly rows?: readonly Record<string, unknown>[];
+    readonly columns?: readonly SemaphorResultColumn[];
+    readonly columnKeyMap?: QueryColumnKeyMap;
+    readonly comparisonMetadata?: ComparisonMetadataMap;
+};
+/**
+ * `screen`: the columns the table renders (comparison change values are drawn
+ * inside the comparison cell). `export`: the columns a download writes
+ * (comparison change values are their own columns, per the presentation).
+ */
+export type TableViewProjection = 'screen' | 'export';
+export type TableViewInput = {
+    /**
+     * The card as its rows were queried: for a builder table its config is the
+     * query's final config (the drill applied, then the viewer's sort), so the
+     * view shows exactly the sort the rows were queried with.
+     */
+    readonly card: TCard;
+    /** Decides `sortMode` for SQL and Python tables. */
+    readonly paginationMode: 'client' | 'server';
+    readonly result: TableResultShape;
+    readonly settings?: ViewerTableSettings;
+    /** Default `screen`. */
+    readonly projection?: TableViewProjection;
+};
+export type TableViewColumn = {
+    readonly outputKey: string;
+    /** The addressable column this output key belongs to; absent when not addressable. */
+    readonly columnId?: TableColumnId;
+    readonly part: 'base' | 'pivot-member' | 'comparison';
+    readonly visible: boolean;
+    /** Final header: viewer name, else today's pivot, comparison or field label, else the output key. */
+    readonly label: string;
+};
+export type ColumnPanelItem = {
+    readonly columnId: TableColumnId;
+    readonly label: string;
+    readonly authorLabel: string;
+    readonly hidden: boolean;
+    /** Added by the author since the viewer arranged this table. */
+    readonly isNew: boolean;
+    /** False for the last visible addressable column. */
+    readonly canHide: boolean;
+    readonly sort?: 'asc' | 'desc';
+};
+export type ColumnPanel = {
+    readonly available: false;
+    readonly reason: 'card-type' | 'author-disabled' | 'no-addressable-columns';
+} | {
+    readonly available: true;
+    readonly items: readonly ColumnPanelItem[];
+    readonly canReset: boolean;
+};
+/** query: builder tables, sorted in the query. browser: SQL/Python, all rows loaded, saved. page-only: SQL/Python, server pagination, never saved. */
+export type TableSortMode = 'query' | 'browser' | 'page-only';
+export type TableView = {
+    /** Every output key in display order, hidden ones included. */
+    readonly columns: readonly TableViewColumn[];
+    /** Output keys to show, in order. The only column list downloads use. */
+    readonly visibleKeys: readonly string[];
+    /** outputKey -> header, for every key. */
+    readonly labels: Readonly<Record<string, string>>;
+    readonly sortMode: TableSortMode;
+    /** The table's controlled sort, by output key. */
+    readonly clientSort: readonly {
+        readonly outputKey: string;
+        readonly desc: boolean;
+    }[];
+    readonly panel: ColumnPanel;
+    /** The settings after reconciling with this card and result. */
+    readonly settings?: ViewerTableSettings;
+    /** Setting entries that match no column (ignored; cleaned on the next save). */
+    readonly dropped: readonly TableColumnId[];
+    /**
+     * Hide, order or rename settings apply (never with customization off): the
+     * "Your columns" marks and Reset columns. A sort alone shows by its arrow.
+     */
+    readonly isCustomized: boolean;
+    /**
+     * The viewer can sort through the view: any table or detail table outside
+     * `page-only` mode. With customization off, only the sort applies, and it
+     * is never saved (PLAN B30).
+     */
+    readonly canSort: boolean;
+    /** The author's arrangement of the addressable columns; order edits normalize against it. */
+    readonly author: {
+        readonly order: readonly TableColumnId[];
+    };
+};
+export type TableColumnEdit = {
+    readonly type: 'hide' | 'show';
+    readonly columnId: TableColumnId;
+}
+/** `beforeColumnId: null` moves to the end. */
+ | {
+    readonly type: 'move';
+    readonly columnId: TableColumnId;
+    readonly beforeColumnId: TableColumnId | null;
+}
+/** An empty name or the author's label clears the rename. */
+ | {
+    readonly type: 'rename';
+    readonly columnId: TableColumnId;
+    readonly label: string;
+}
+/** The renderer's sort state, by output key. */
+ | {
+    readonly type: 'sort';
+    readonly sorting: readonly {
+        readonly outputKey: string;
+        readonly desc: boolean;
+    }[];
+} | {
+    readonly type: 'reset';
+};
+type ConfigField = DetailField | GroupByField | MetricField;
+/** Unique keys across rows, in first-seen order (the renderer's key list). */
+export declare function collectResultKeys(rows: readonly Record<string, unknown>[] | undefined): string[];
+/**
+ * The column ids a builder table's configuration defines, known without
+ * running it. `undefined` for SQL and Python tables: their columns come only
+ * from a result. The author impact warning uses it.
+ */
+export declare function listConfiguredTableColumnIds(card: TCard): ReadonlySet<TableColumnId> | undefined;
+/** The generated count column exists whenever its table does. */
+export declare function isGeneratedCountColumnId(columnId: string): boolean;
+/** The one resolver for render, the column panel and every download. Pure. */
+export declare function resolveTableView(input: TableViewInput): TableView;
+/** The configured field a column id names: one field, or `undefined` when none or several match. */
+export declare function findFieldForColumnId(card: TCard, columnId: TableColumnId): ConfigField | undefined;
+/**
+ * The card config the query uses: for builder tables, `sortByColumns` from
+ * `settings.sort` when present (`[]` = unsorted); otherwise `card.config`
+ * unchanged (same reference). A sort on a column the author hid is ignored,
+ * as the view ignores it. Each entry names its column by id and result alias,
+ * which `findSortTarget` resolves in the query builder. Called only by
+ * `buildCardQueryContext`, with the card at its current drill level: the
+ * config the table resolves its columns against.
+ */
+export declare function effectiveTableConfig(card: TCard, settings: ViewerTableSettings | undefined): CardConfig | undefined;
+export {};

package/dist/types/lib/dashboard-viewer/use-table-view.d.ts

@@ -0,0 +1,51 @@
+import { TCard } from '../types/common-types.js';
+import { QueryColumnKeyMap } from '../types/explorer-types.js';
+import { ComparisonMetadataMap } from '../types/query-types.js';
+import { SemaphorResultColumn } from '../../shared/analytics-protocol/index.js';
+import { TableColumnEdit, TableResultShape, TableView } from './table-view.js';
+import { TableColumnEditResult } from './table-view-edit.js';
+import { ViewerTableSettings } from '../../shared/dashboard-viewer/index.js';
+import { ExportViewerTable } from './export-table-view.js';
+export type TableViewHandle = {
+    readonly view: TableView | undefined;
+    /** Applies one column edit for this viewer; never changes the dashboard. */
+    readonly edit: (edit: TableColumnEdit) => TableColumnEditResult['status'];
+    /** The settings the view was built from, for the table renderer. */
+    readonly settings: ViewerTableSettings | undefined;
+    /** False while the dashboard or a visual is being edited: the author sees the authored table. */
+    readonly isViewerContext: boolean;
+};
+/**
+ * One table card and its result: the view plus an edit function. `card` is the
+ * card as rendered: its config is the one its rows were queried with, so the
+ * view's sort is the query's.
+ */
+export declare function useTableView(card: TCard, result: TableResultShape | undefined): TableViewHandle;
+/**
+ * What a table renderer takes from the viewer layer (`DataTableProps.viewerTable`):
+ * the settings, and the view the card resolved from them, which the table
+ * renders as is so the card, its column panel and its table show one view.
+ */
+export type ViewerDataTable = ExportViewerTable & {
+    readonly view?: TableView;
+};
+/**
+ * A dashboard table rendered for a viewer: the view handle, the
+ * `viewerTable` the renderer takes, and a sort handler that keeps the viewer's
+ * sort in their settings. The dashboard card and its expanded view both use
+ * it, so the two always show the same columns.
+ */
+export declare function useViewerDataTable(card: TCard, result: {
+    readonly rows: readonly Record<string, unknown>[];
+    readonly columns?: readonly SemaphorResultColumn[];
+    readonly columnKeyMap?: QueryColumnKeyMap;
+    readonly comparisonMetadata?: ComparisonMetadataMap;
+} | undefined): {
+    readonly handle: TableViewHandle;
+    readonly viewerTable: ViewerDataTable | undefined;
+    /** Sends a viewer's header sort to their settings; `false` outside a viewer context. */
+    readonly sortAsViewer: (sorting: readonly {
+        readonly id: string;
+        readonly desc?: boolean;
+    }[]) => boolean;
+};

package/dist/types/lib/dashboard-viewer/viewer-state-client.d.ts

@@ -0,0 +1,72 @@
+import { Bookmark, BookmarkState, BookmarkSummary, BookmarkUsage, BookmarkVisibility, ViewerErrorCode, ViewerTableSettings } from '../../shared/dashboard-viewer/index.js';
+export type ViewerClientError = {
+    /** `network`: the request never completed. `failed`: the server answered with an error it didn't name. */
+    readonly code: ViewerErrorCode | 'network' | 'failed';
+    readonly message: string;
+    readonly currentRevision?: number;
+};
+export type UpdateBookmarkResult = {
+    readonly ok: true;
+    readonly bookmark: Bookmark;
+} | {
+    readonly ok: false;
+    readonly conflict: {
+        readonly currentRevision: number;
+    };
+};
+export type ViewerStateClient = {
+    /**
+     * The dashboard and viewer this client belongs to. One client per viewer:
+     * a different viewer gets a new client, and the old one's pending writes
+     * are dropped. Query caches are keyed by it.
+     */
+    readonly viewerKey: string;
+    /** Queues a remembered-settings write for one card (`undefined` clears it). Never rejects; failures go to `onError`. */
+    saveTableSettings(cardId: string, settings: ViewerTableSettings | undefined): void;
+    /** Queues a clear of every card; drops pending per-card writes. */
+    clearAllTableSettings(): void;
+    /** Resolves when the queue is empty. */
+    flush(): Promise<void>;
+    readonly bookmarks: {
+        list(): Promise<readonly BookmarkSummary[]>;
+        get(bookmarkId: string): Promise<Bookmark>;
+        create(input: {
+            readonly name: string;
+            readonly state: BookmarkState;
+            readonly makeDefault: boolean;
+            readonly visibility?: BookmarkVisibility;
+        }): Promise<Bookmark>;
+        update(bookmarkId: string, input: {
+            readonly expectedRevision: number;
+            readonly name?: string;
+            readonly state?: BookmarkState;
+            readonly visibility?: BookmarkVisibility;
+        }): Promise<UpdateBookmarkResult>;
+        remove(bookmarkId: string): Promise<void>;
+        setDefault(bookmarkId: string | null): Promise<void>;
+        /** People who can edit the dashboard; rejects with `forbidden` otherwise. */
+        usage(): Promise<BookmarkUsage>;
+    };
+    dispose(): void;
+};
+export declare class ViewerRequestError extends Error {
+    readonly code: ViewerClientError['code'];
+    readonly currentRevision?: number;
+    constructor(error: ViewerClientError);
+}
+/**
+ * One client per mounted dashboard (TECH-SPEC 7). Remembered-settings writes
+ * go through one queue: at most one request in flight, the latest pending
+ * change per card, and a clear-all drops pending card writes. Bookmark calls
+ * are plain requests.
+ */
+export declare function createViewerStateClient(options: {
+    readonly apiServiceUrl: string;
+    readonly dashboardId: string;
+    /** `<dashboardId>|<viewer identity>`, see `ViewerStateClient.viewerKey`. */
+    readonly viewerKey: string;
+    /** `undefined` when this client no longer belongs to the session: nothing is sent. */
+    readonly getAccessToken: () => string | undefined;
+    readonly onError?: (error: ViewerClientError) => void;
+    readonly fetchImpl?: typeof fetch;
+}): ViewerStateClient;