react-semaphor 0.1.504 → 0.1.506

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

@@ -0,0 +1,2 @@
+import { DataTableProps } from './types/data-table.js';
+export declare function DataTable(props: DataTableProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,97 @@
+import { ColumnSettings, ColumnSettingsMap } from '../types/data-table.js';
+import { default as React } from 'react';
+import { SortingState, RowSelectionState, VisibilityState, ColumnSizingState } from '@tanstack/react-table';
+import { ComparisonMetadataMap } from '../../../../lib/types/query-types.js';
+import { CardConfig, QueryColumnKeyMap } from '../../../../lib/types/explorer-types.js';
+import { RawTemporalValueKind, SemaphorResultColumn } from '../../../../shared/analytics-protocol/index.js';
+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';
+interface DataTableLogicProps {
+    data: any[];
+    resultColumns?: SemaphorResultColumn[];
+    columnKeyMap?: QueryColumnKeyMap;
+    totalsData?: any[];
+    formattingFullRows?: any[];
+    formattingRenderContext?: ConditionalFormattingRenderContext;
+    totalsByColumnId?: Record<string, string | number | null>;
+    pageSize?: number;
+    comparisonMetadata?: ComparisonMetadataMap;
+    columnSettings?: ColumnSettingsMap;
+    columnVisibility?: VisibilityState;
+    initialColumnVisibility?: VisibilityState;
+    defaultSelectColumnVisible?: boolean;
+    onSelectColumnVisibleChange?: (visible: boolean) => void;
+    onInitializeColumnVisibility?: (columnIds: string[]) => void;
+    onUpdateAllColumnVisibility?: (visibility: VisibilityState) => void;
+    onColumnSettingsChange?: (columnId: string, settings: ColumnSettings, baseline: ColumnSettings, rawTemporalValueKind?: RawTemporalValueKind) => void;
+    onResetColumnSettings?: (columnId: string) => void;
+    onResetAllColumnSettings?: () => void;
+    onBaseFormattingChange?: (formatting: TableBaseFormatting) => void;
+    onColumnVisibilityChange?: (columnId: string, isVisible: boolean) => void;
+    onSortChange?: (sorting: SortingState) => void;
+    sortState?: SortingState;
+    onColumnReorder?: (request: ColumnReorderRequest) => boolean;
+    columnSizing?: ColumnSizingState;
+    onColumnSizingChange?: (updater: ColumnSizingState | ((old: ColumnSizingState) => ColumnSizingState)) => void;
+    card?: any;
+    effectiveCardConfig?: CardConfig;
+    paginationMetadata?: any;
+    onPaginationChange?: (pageIndex: number, pageSize: number) => void;
+    suppressSortControls?: boolean;
+    suppressCellHoverCards?: boolean;
+    headerTextClassName?: string;
+    headerWrapText?: boolean;
+    appearanceWrapText?: boolean;
+}
+export declare function useDataTableLogic(props: DataTableLogicProps): {
+    table: import('@tanstack/table-core').Table<any>;
+    columnSettingsToUse: ColumnSettingsMap;
+    selectColumnVisible: boolean;
+    columnVisibilityToUse: VisibilityState;
+    handleColumnVisibilityChange: (columnId: string, isVisible: boolean) => void;
+    resetColumnSettings: () => void;
+    resetAllColumnSettings: () => void;
+    handleSelectColumnVisibleChange: (visible: boolean) => void;
+    selectedRowsCount: number;
+    exportData: {
+        rows: Record<string, any>[];
+        selectedRows: Record<string, any>[];
+        visibleColumns: string[];
+        columnSettings: ColumnSettingsMap;
+        contextTimezone: string | undefined;
+        browserTimezone: string;
+    };
+    globalFilter: string;
+    setGlobalFilter: React.Dispatch<React.SetStateAction<string>>;
+    setRowSelection: React.Dispatch<React.SetStateAction<RowSelectionState>>;
+    columnSettingsOpen: boolean;
+    activeColumnId: string | null;
+    activeColumnSettings: ColumnSettings;
+    activeColumnBaseStyle: TableBaseStyle;
+    handleColumnSettingsChange: (next: ColumnSettings) => void;
+    handleColumnBaseStyleChange: (next: TableBaseStyle) => void;
+    isHandlingVisibilityChange: React.RefObject<boolean>;
+    themeStyle: import('../../../index.js').StyleProps | undefined;
+    tableRef: React.RefObject<any>;
+    internalColumnSettings: ColumnSettingsMap;
+    internalSelectColumnVisible: boolean;
+    getRowStyle: (_row: any) => React.CSSProperties;
+    setColumnSettingsOpen: React.Dispatch<React.SetStateAction<boolean>>;
+    columns: import('@tanstack/table-core').ColumnDef<import('../types/data-table.js').DataTableRow>[];
+    internalColumnVisibility: VisibilityState;
+    totalColumns: number;
+    totalRows: number;
+    isTablePrintDisplayMode: boolean;
+    onSortChange: ((sorting: SortingState) => void) | undefined;
+    paginationMode: import('../utils/pagination-utils.js').PaginationMode;
+    paginationMetadata: any;
+    contextTimezone: string | undefined;
+    browserTimezone: string;
+    valueFormatPreferences: import('../../../../shared/value-format-preferences/index.js').ResolvedValueFormatPreferences | null;
+    resolveBoundCurrency: (target: import('../../../index.js').CurrencyPresentationTarget) => string | undefined;
+    temporalPresentation: import('../../../../lib/formatters/regular-table-temporal-presentation.js').RegularTableTemporalPresentation;
+    rawTemporalPresentation: RawTemporalPresentation | undefined;
+    usesDeclaredSqlRawTemporalPresentation: boolean;
+};
+export {};

package/dist/types/components/visual/data-table/hooks/use-sql-raw-temporal-format-draft.d.ts

@@ -0,0 +1,15 @@
+import { ColumnSettings, PersistedColumnSettings } from '../types/data-table.js';
+import { RawTemporalValueKind } from '../../../../shared/analytics-protocol/index.js';
+export declare function useSqlRawTemporalFormatDraft(input: {
+    enabled: boolean;
+    settings: ColumnSettings;
+    persistedSettings?: PersistedColumnSettings;
+    valueKind?: RawTemporalValueKind;
+    onSettingsChange: (settings: ColumnSettings) => void;
+}): {
+    draft: string;
+    error: string | undefined;
+    selectCustom: () => void;
+    update: (customFormat: string) => void;
+    restoreLastValid: () => void;
+};

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

@@ -0,0 +1,30 @@
+import { PaginationState, SortingState } from '@tanstack/react-table';
+import { TCard } from '../../../../lib/types/common-types.js';
+import { PaginationMetadata } from '../../../../lib/types/explorer-types.js';
+type UseTableQueryStateOptions = {
+    card?: TCard;
+    dataLength: number;
+    pageSize?: number;
+    paginationMetadata?: PaginationMetadata;
+    onPaginationChange?: (pageIndex: number, pageSize: number) => void;
+    sortState?: SortingState;
+    onSortChange?: (sorting: SortingState) => void;
+    allowSqlLocalSortingWhenServerPaginated?: boolean;
+};
+export declare function useTableQueryState({ card, dataLength, pageSize, paginationMetadata, onPaginationChange, sortState, onSortChange, allowSqlLocalSortingWhenServerPaginated, }: UseTableQueryStateOptions): {
+    canSort: boolean;
+    canUseLocalSorting: boolean;
+    effectivePageSize: number;
+    handlePaginationChange: (updater: PaginationState | ((old: PaginationState) => PaginationState)) => void;
+    handleSortChange: (updaterOrValue: SortingState | ((old: SortingState) => SortingState)) => void;
+    isTablePrintDisplayMode: boolean;
+    pagination: {
+        pageIndex: number;
+        pageSize: number;
+    };
+    paginationMode: import('../utils/pagination-utils.js').PaginationMode;
+    resetClientPagination: (nextPageSize?: number) => void;
+    shouldSyncSortWithExternal: boolean;
+    sorting: SortingState;
+};
+export {};

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

@@ -0,0 +1,9 @@
+import { ReactNode } from 'react';
+interface OverflowCellProps {
+    children: ReactNode;
+    value: string;
+    className?: string;
+    style?: React.CSSProperties;
+}
+export declare function OverflowCell({ children, value, className, style, }: OverflowCellProps): import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,17 @@
+import { TCard } from '../../../lib/types/common-types.js';
+import { TableConditionalFormatting } from '../../../lib/table-formatting/index.js';
+import { QueryColumnKeyMap } from '../../../lib/types/explorer-types.js';
+export type TableVisualSettingsFocus = 'style' | 'columns' | 'conditional-formatting';
+export type TableConditionalFormattingColumnOption = {
+    value: string;
+    label: string;
+};
+export declare const UNASSIGNED_CONDITIONAL_FORMATTING_COLUMN_ID = "__semaphor_unassigned_trigger__";
+export declare function supportsTableConditionalFormatting(cardType: string | undefined): cardType is "table";
+export declare function getTableConditionalFormattingColumnOptions(card: TCard | undefined, queryResultColumns?: string[], columnKeyMap?: QueryColumnKeyMap): {
+    label: string;
+    value: string;
+}[];
+export declare function getTableOutputColumnOptions(card: TCard | undefined, queryResultColumns?: string[]): TableConditionalFormattingColumnOption[];
+export declare function getTableConditionalFormattingColumnIds(card: TCard | undefined, queryResultColumns?: string[]): string[];
+export declare function withTableConditionalFormatting(card: TCard, conditionalFormatting: TableConditionalFormatting): TCard;

package/dist/types/components/visual/data-table/table-conditional-formatting-rule-model.d.ts

@@ -0,0 +1,33 @@
+import { ConditionalFormatRule } from '../../../lib/table-formatting/index.js';
+import { TableConditionalFormattingColumnOption } from './table-conditional-formatting-authoring.js';
+export type ConditionalRuleKind = 'comparison' | 'topBottom' | 'colorScale' | 'dataBar';
+export type ComparisonRuleOperator = 'gt' | 'gte' | 'lt' | 'lte' | 'eq' | 'neq' | 'between' | 'contains' | 'blank' | 'notBlank';
+export declare const COMPARISON_OPERATOR_OPTIONS: Array<{
+    value: ComparisonRuleOperator;
+    label: string;
+}>;
+export declare function isUnassignedTriggerColumnId(columnId: string | undefined): columnId is "__semaphor_unassigned_trigger__";
+export declare function getRuleKind(rule: ConditionalFormatRule): ConditionalRuleKind;
+export declare function getConditionalOperator(rule: ConditionalFormatRule): ComparisonRuleOperator;
+export declare function getConditionalValue(rule: ConditionalFormatRule): string;
+export declare function getConditionalMaxValue(rule: ConditionalFormatRule): string;
+export declare function getNumericInputValue(value: unknown): string;
+export declare function parseOptionalNumber(value: string): number | undefined;
+export declare function parseRequiredNumber(value: string, fallback: number): number;
+export declare function describeRule(rule: ConditionalFormatRule): string;
+export declare function getConditionColumnId(rule: ConditionalFormatRule): string;
+export declare function normalizeColumnOptions(availableColumns: Array<string | TableConditionalFormattingColumnOption>): TableConditionalFormattingColumnOption[];
+export declare function isVisualRangeRule(rule: ConditionalFormatRule): boolean;
+export declare function isVisualRangeKind(kind: ConditionalRuleKind): kind is "colorScale" | "dataBar";
+export declare function isRuleReadyToApply(rule: ConditionalFormatRule): boolean;
+export declare function reconcileDraftEnabledState(previousRule: ConditionalFormatRule, nextRule: ConditionalFormatRule): ConditionalFormatRule;
+export declare function createConditionalRule({ columnId, columnLabel, existingRule, index, kind, operator, value, conditionColumnId, }: {
+    columnId: string;
+    columnLabel?: string;
+    existingRule?: ConditionalFormatRule;
+    index: number;
+    kind?: ConditionalRuleKind;
+    operator?: ComparisonRuleOperator;
+    value?: unknown;
+    conditionColumnId?: string;
+}): ConditionalFormatRule | undefined;

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

@@ -0,0 +1,9 @@
+import { TChartType } from '../../../lib/charts/types.js';
+import { TCard } from '../../../lib/types/common-types.js';
+type TableSettingsToolbarButtonProps = {
+    card: TCard;
+    effectiveCardType?: TChartType;
+    queryResultColumns?: string[];
+};
+export declare function TableSettingsToolbarButton({ card, effectiveCardType, queryResultColumns, }: TableSettingsToolbarButtonProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

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

@@ -0,0 +1,6 @@
+interface TableSkeletonProps {
+    columns?: number;
+    rows?: number;
+}
+export declare function TableSkeleton({ columns, rows }: TableSkeletonProps): import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,39 @@
+import { default as React } from 'react';
+import { SortingState } from '@tanstack/react-table';
+import { TCard } from '../../../lib/types/common-types.js';
+import { DataTableProps } from './types/data-table.js';
+import { Interaction } from '../../../lib/types/interaction-types.js';
+import { ClickContextResult } from '../../../lib/interactions/get-click-context-from-chartjs.js';
+import { ComparisonMetadataMap } from '../../../lib/types/query-types.js';
+import { SemaphorResultColumn } from '../../../shared/analytics-protocol/index.js';
+import { QueryColumnKeyMap } from '../../../lib/types/explorer-types.js';
+type TableVisualProps = {
+    data: any[];
+    resultColumns?: SemaphorResultColumn[];
+    columnKeyMap?: QueryColumnKeyMap;
+    totalsData?: any[];
+    formattingFullRows?: any[];
+    totalsByColumnId?: Record<string, string | number | null>;
+    card: TCard;
+    comparisonMetadata?: ComparisonMetadataMap;
+    onSortChange?: (sorting: SortingState) => void;
+    sortState?: SortingState;
+    paginationMetadata?: any;
+    onPaginationChange?: (pageIndex: number, pageSize: number) => void;
+    isLoading?: boolean;
+    suppressSortControls?: boolean;
+    suppressCellHoverCards?: boolean;
+    columnSizing?: DataTableProps['columnSizing'];
+    onColumnSizingChange?: DataTableProps['onColumnSizingChange'];
+    onColumnResizeStateChange?: DataTableProps['onColumnResizeStateChange'];
+    showColumnResizeHandles?: boolean;
+    frameId?: string;
+    sheetId?: string;
+    onMultipleInteractions?: (matches: Interaction[], context: ClickContextResult, position?: {
+        x: number;
+        y: number;
+    }) => void;
+};
+declare function TableVisual({ data, resultColumns, columnKeyMap, totalsData, formattingFullRows, totalsByColumnId, card, comparisonMetadata, onSortChange, sortState, paginationMetadata, onPaginationChange, isLoading, suppressSortControls, suppressCellHoverCards, columnSizing: controlledColumnSizing, onColumnSizingChange: controlledOnColumnSizingChange, onColumnResizeStateChange, showColumnResizeHandles, frameId, sheetId, onMultipleInteractions, }: TableVisualProps): import("react/jsx-runtime").JSX.Element;
+declare const _default: React.MemoExoticComponent<typeof TableVisual>;
+export default _default;

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

@@ -0,0 +1,286 @@
+import { TCard } from '../../../../lib/types/common-types.js';
+import { CSSProperties } from 'react';
+import { Column, SortingState, ColumnSizingState } from '@tanstack/react-table';
+import { PaginationMetadata, QueryColumnKeyMap } from '../../../../lib/types/explorer-types.js';
+import { Interaction } from '../../../../lib/types/interaction-types.js';
+import { ClickContextResult } from '../../../../lib/interactions/get-click-context-from-chartjs.js';
+import { ComparisonMetadataMap } from '../../../../lib/types/query-types.js';
+import { ColumnReorderRequest } from '../../shared/utils/table-column-order.js';
+import { ConditionalFormattingRenderContext, TableBaseFormatting, TableBaseStyle } from '../../../../lib/table-formatting/table-formatting-types.js';
+import { ColumnTextWrap } from '../../../../lib/table-formatting/table-text-flow.js';
+import { RawTemporalValueKind, SemaphorResultColumn } from '../../../../shared/analytics-protocol/index.js';
+export type { ColumnTextWrap } from '../../../../lib/table-formatting/table-text-flow.js';
+export interface ColorRange {
+    min: number;
+    max: number;
+    color: string;
+    applyTo: 'cell' | 'row';
+}
+export interface LinkFormat {
+    urlTemplate: string;
+    labelType: 'value' | 'static' | 'column';
+    staticLabel?: string;
+    labelColumn?: string;
+    openInNewTab: boolean;
+}
+/** Historical per-column totals shape. Runtime totals are table-level now. */
+export type TotalsBehavior = 'sum' | 'avg' | 'count' | 'label' | 'none';
+export interface ColumnSettings {
+    type: 'none' | 'text' | 'number' | 'date' | 'badge' | 'link' | 'progress';
+    inheritMetricFormat?: boolean;
+    textAlign: 'left' | 'center' | 'right';
+    width: number;
+    minWidth?: number;
+    maxWidth?: number;
+    textOverflow?: 'ellipsis' | 'wrap' | 'clip';
+    textWrap: ColumnTextWrap;
+    /** Deprecated/inert. Totals are controlled by tablePrefs.tableStyle.totals. */
+    totalsBehavior?: TotalsBehavior;
+    totalsLabel?: string;
+    numberFormat: {
+        style: 'decimal' | 'currency' | 'percent' | 'scientific';
+        currency?: string;
+        locale?: string;
+        minimumFractionDigits?: number;
+        maximumFractionDigits?: number;
+        useGrouping?: boolean;
+        percentValueMode?: 'fraction' | 'whole';
+        scale?: number;
+        compact?: boolean;
+        negativeStyle?: 'minus' | 'parentheses';
+        prefix?: string;
+        suffix?: string;
+        showDataBar: boolean;
+        dataBarColor: string;
+        dataBarMinValue?: number;
+        dataBarMaxValue?: number;
+        /**
+         * When true, render the cell bg with a heatmap intensity tint scaled
+         * across the column's value range. Composes with the existing text
+         * color/color-range logic (tint is bg only). `showDataBar` takes
+         * precedence when both are set — per the canonical design, a cell is
+         * either a data-bar or a heatmap, never both.
+         */
+        showHeatmap?: boolean;
+    };
+    dateFormat: {
+        format: string;
+        useCustomFormat: boolean;
+        customFormat: string;
+        useRelativeTime: boolean;
+        timezone?: string;
+        sourceTimezone?: string;
+    };
+    linkFormat: LinkFormat;
+    colorRanges: ColorRange[];
+}
+/**
+ * Row rhythm for the whole table. Authors pick one per card; undefined
+ * falls back to 'compact' (the canonical default — dense scanning, matches
+ * the Linear-style spec). Drives row padding, cell font size, and header
+ * font size via a shared density spec in DataTable.
+ */
+export type TableDensity = 'dense' | 'compact' | 'standard' | 'comfortable' | 'spacious';
+export type TableHeaderStyle = 'plain' | 'filled' | 'accent';
+export type TableGridLines = 'none' | 'outer' | 'inner' | 'horizontal' | 'vertical' | 'top' | 'right' | 'bottom' | 'left' | 'full';
+export type TableTotalsFontWeight = 'normal' | 'medium' | 'semibold' | 'bold';
+export type TableTotalsStylePreferences = {
+    enabled?: boolean;
+    backgroundColor?: string;
+    textColor?: string;
+    fontWeight?: TableTotalsFontWeight;
+    borderTop?: boolean;
+    borderTopStyle?: 'solid' | 'dashed' | 'dotted' | 'double';
+    borderTopColor?: string;
+};
+export type TableStylePreferences = {
+    headerStyle?: TableHeaderStyle;
+    headerBackgroundColor?: string;
+    headerTextColor?: string;
+    headerWrapText?: boolean;
+    stripedRows?: boolean;
+    gridLines?: TableGridLines;
+    wrapText?: boolean;
+    totals?: TableTotalsStylePreferences;
+};
+export type TablePreferences = {
+    columnSettingsMap?: PersistedColumnSettingsMap;
+    baseFormatting?: import('../../../../lib/table-formatting/table-formatting-types.js').TableBaseFormatting;
+    conditionalFormatting?: import('../../../../lib/table-formatting/table-formatting-types.js').TableConditionalFormatting;
+    selectColumnVisible?: boolean;
+    columnVisibility?: Record<string, boolean>;
+    columnSizing?: ColumnSizingState;
+    pageSize?: number;
+    enableDevModePagination?: boolean;
+    forceClientPagination?: boolean;
+    density?: TableDensity;
+    tableStyle?: TableStylePreferences;
+};
+export type PersistedColumnSettings = Omit<Partial<ColumnSettings>, 'numberFormat' | 'dateFormat'> & {
+    numberFormat?: Partial<ColumnSettings['numberFormat']>;
+    /** Sparse persisted date settings; conditional requirements are enforced by the serializer. */
+    dateFormat?: Partial<ColumnSettings['dateFormat']>;
+};
+export type PersistedColumnSettingsMap = Record<string, PersistedColumnSettings>;
+export type ColumnSettingsMap = Record<string, ColumnSettings>;
+export type DataTableRow = Record<string, string | number | null>;
+export interface DataTableProps {
+    card: TCard;
+    data: DataTableRow[];
+    resultColumns?: SemaphorResultColumn[];
+    columnKeyMap?: QueryColumnKeyMap;
+    /**
+     * Optional dataset used only for table-level totals. Document print slices pass
+     * the visible page rows as `data` and the full query result here so the final
+     * footer represents the whole report table, not only the last page slice.
+     */
+    totalsData?: DataTableRow[];
+    /**
+     * Optional full formatting domain for conditional-formatting rules whose ranges
+     * must be computed from the whole table. This is intentionally separate from
+     * totalsData: totalsData controls footer aggregation, while formattingFullRows
+     * controls print-safe conditional-formatting ranges.
+     */
+    formattingFullRows?: DataTableRow[];
+    formattingRenderContext?: ConditionalFormattingRenderContext;
+    /**
+     * Optional precomputed totals keyed by rendered column id. Document flat-table
+     * reports use this for backend grand totals over the full filtered result.
+     */
+    totalsByColumnId?: Record<string, string | number | null>;
+    comparisonMetadata?: ComparisonMetadataMap;
+    exportFileName?: string;
+    pageSize?: number;
+    columnSettings?: ColumnSettingsMap;
+    onColumnSettingsChange?: (columnId: string, settings: ColumnSettings, baseline: ColumnSettings, rawTemporalValueKind?: RawTemporalValueKind) => void;
+    onResetColumnSettings?: (columnId: string) => void;
+    onResetAllColumnSettings?: () => void;
+    onBaseFormattingChange?: (formatting: TableBaseFormatting) => void;
+    columnSizing?: ColumnSizingState;
+    onColumnSizingChange?: (sizing: ColumnSizingState | ((old: ColumnSizingState) => ColumnSizingState)) => void;
+    onColumnResizeStateChange?: (isResizing: boolean) => void;
+    showColumnResizeHandles?: boolean;
+    columnVisibility?: Record<string, boolean>;
+    initialColumnVisibility?: Record<string, boolean>;
+    onColumnVisibilityChange?: (columnId: string, isVisible: boolean) => void;
+    onShowAllColumns?: () => void;
+    onHideAllColumns?: () => void;
+    defaultSelectColumnVisible?: boolean;
+    onSelectColumnVisibleChange?: (visible: boolean) => void;
+    onInitializeColumnVisibility?: (columnIds: string[]) => void;
+    onUpdateAllColumnVisibility?: (visibility: Record<string, boolean>) => void;
+    sortState?: SortingState;
+    onSortChange?: (sorting: SortingState) => void;
+    onColumnReorder?: (request: ColumnReorderRequest) => boolean;
+    paginationMetadata?: PaginationMetadata;
+    onPaginationChange?: (pageIndex: number, pageSize: number) => void;
+    isLoading?: boolean;
+    suppressSortControls?: boolean;
+    suppressCellHoverCards?: boolean;
+    frameId?: string;
+    sheetId?: string;
+    onMultipleInteractions?: (matches: Interaction[], context: ClickContextResult, position?: {
+        x: number;
+        y: number;
+    }) => void;
+}
+export interface DataTableColumnSettingsProps {
+    column: Column<any, unknown> | null;
+    settings: ColumnSettings;
+    onSettingsChange: (settings: ColumnSettings) => void;
+    baseStyle?: TableBaseStyle;
+    onBaseStyleChange?: (style: TableBaseStyle) => void;
+    onApply?: () => void;
+    onReset: () => void;
+    onResetAll: () => void;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    availableColumns?: string[];
+    tableType?: 'data' | 'pivot' | 'aggregate';
+    /** Whether this is a raw SQL card (bypasses timezone-aware query pipeline) */
+    isSqlCard?: boolean;
+    /** Sparse authored bytes before default hydration. */
+    persistedSettings?: PersistedColumnSettings;
+    /** True only for free-form SQL with normalized-empty Python. */
+    usesDeclaredSqlRawTemporalPresentation?: boolean;
+    /** Classified temporal semantics for the active SQL-only result column. */
+    rawTemporalValueKind?: RawTemporalValueKind;
+}
+export interface DataTableToolbarProps {
+    card: TCard;
+    globalFilter: string;
+    totalColumns: number;
+    totalRows: number;
+    onGlobalFilterChange: (value: string) => void;
+    selectedRowsCount: number;
+    columns: Column<any, unknown>[];
+    selectColumnVisible: boolean;
+    onToggleSelectColumn: (visible: boolean) => void;
+    onColumnVisibilityChange?: (columnId: string, isVisible: boolean) => void;
+    data: {
+        rows: Record<string, any>[];
+        selectedRows: Record<string, any>[];
+        visibleColumns: string[];
+        columnSettings: ColumnSettingsMap;
+        contextTimezone?: string;
+        browserTimezone?: string;
+    };
+    exportFileName?: string;
+}
+export type DataTablePaginationAppearance = {
+    containerStyle?: CSSProperties;
+    controlStyle?: CSSProperties;
+    textStyle?: CSSProperties;
+};
+export interface DataTablePaginationProps {
+    totalColumns: number;
+    pageCount: number;
+    pageIndex: number;
+    pageSize: number;
+    rowCount: number;
+    selectedRowCount: number;
+    setPageIndex: (pageIndex: number) => void;
+    setPageSize: (pageSize: number) => void;
+    canPreviousPage: boolean;
+    canNextPage: boolean;
+    previousPage: () => void;
+    nextPage: () => void;
+    onClearSelection: () => void;
+    onPageSizePreferenceChange?: (pageSize: number) => void;
+    paginationMode?: 'client' | 'server' | 'disabled';
+    /** Present only when the card's pagination mode is author-switchable
+     *  (raw-SQL table cards in the editor). Turns the row-count text into
+     *  a menu that toggles server vs client pagination. */
+    onPaginationModeChange?: (mode: 'client' | 'server') => void;
+    /** Hide navigation controls while keeping an editor mode control visible. */
+    showPaginationControls?: boolean;
+    showExport?: boolean;
+    card?: TCard;
+    frameId?: string;
+    exportData?: any[];
+    appearance?: DataTablePaginationAppearance;
+}
+export interface ColorPickerProps {
+    color: string;
+    onChange: (color: string) => void;
+    className?: string;
+}
+export declare const DATE_FORMAT_GROUPS: {
+    label: string;
+    formats: {
+        label: string;
+        value: string;
+    }[];
+}[];
+export declare const DATE_FORMATS: {
+    label: string;
+    value: string;
+}[];
+export declare const DATE_FORMAT_TYPES: {
+    label: string;
+    value: string;
+}[];
+export declare const COMMON_TIMEZONES: {
+    label: string;
+    value: string;
+}[];

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

@@ -0,0 +1,74 @@
+import { default as React } from 'react';
+import { parseWithSourceTimezone, formatDate, formatRelativeTime, getTimezoneAbbreviation } from '../../../../shared/format-utils/formatters/date-formatter.js';
+export { getCellTextFlowClassName, getHeaderTextFlowClassName, isAuthoredColumnTextWrapOverride, resolveCellShouldWrapText, resolveCellTextFlow, resolveTextWrapCompatibilityInput, } from '../../../../lib/table-formatting/table-text-flow.js';
+export type { ColumnTextWrap, ResolvedCellTextFlow, } from '../../../../lib/table-formatting/table-text-flow.js';
+export declare const getContrastColor: (hexColor: string) => string;
+export declare const getColumnWidthStyle: (width: string | number) => React.CSSProperties;
+export declare const getDefaultLinkFormat: () => {
+    urlTemplate: string;
+    labelType: "value";
+    staticLabel: string;
+    labelColumn: string;
+    openInNewTab: boolean;
+};
+export declare const getDefaultColumnSettings: () => {
+    type: "none";
+    inheritMetricFormat: boolean;
+    textAlign: "left";
+    width: number;
+    minWidth: number;
+    maxWidth: number;
+    textOverflow: "ellipsis";
+    textWrap: "default";
+    numberFormat: {
+        style: "decimal";
+        currency: string;
+        locale: string;
+        minimumFractionDigits: number;
+        maximumFractionDigits: number;
+        useGrouping: boolean;
+        percentValueMode: "whole";
+        showDataBar: boolean;
+        showHeatmap: boolean;
+        dataBarColor: string;
+        dataBarMinValue: undefined;
+        dataBarMaxValue: undefined;
+    };
+    dateFormat: {
+        format: string;
+        useCustomFormat: boolean;
+        customFormat: string;
+        useRelativeTime: boolean;
+        timezone: string;
+        sourceTimezone: string;
+    };
+    linkFormat: {
+        urlTemplate: string;
+        labelType: "value";
+        staticLabel: string;
+        labelColumn: string;
+        openInNewTab: boolean;
+    };
+    colorRanges: never[];
+};
+export declare const getDefaultColorRange: () => {
+    min: number;
+    max: number;
+    color: string;
+    applyTo: "cell";
+};
+export declare const commonColors: string[];
+export { parseWithSourceTimezone, formatDate, formatRelativeTime, getTimezoneAbbreviation, };
+/**
+ * Resolves the display timezone based on card type and column settings.
+ *
+ * - SQL cards: default to browser timezone (user controls the SQL)
+ * - Card-config cards: default to the live report Calendar (backend already converted)
+ *
+ * @param isSqlCard - Whether this is a raw SQL card
+ * @param settingsTimezone - Explicit timezone from column settings (can be 'auto' or undefined)
+ * @param browserTimezone - User's browser timezone
+ * @param contextTimezone - Live report Calendar timezone
+ */
+export declare function resolveDisplayTimezone(isSqlCard: boolean, settingsTimezone: string | undefined, browserTimezone: string, contextTimezone?: string): string;
+export declare const getTimezoneName: (timezone: string) => string;

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

@@ -0,0 +1,31 @@
+import { TCard } from '../../../../lib/types/common-types.js';
+import { ColumnSettingsMap } from '../types/data-table.js';
+import { CardNumericPresentationContext } from '../../../../lib/formatters/numeric-presentation.js';
+/**
+ * Convert data to CSV format
+ */
+export declare function convertToCSV(data: Record<string, any>[], includeHeaders?: boolean): string;
+/**
+ * Convert data to CSV format with formatting preserved
+ */
+export declare function convertToCSVWithFormatting(data: Record<string, any>[], columnSettings: ColumnSettingsMap, visibleColumns: string[], includeHeaders?: boolean, contextTimezone?: string, browserTimezone?: string, isSqlCard?: boolean, card?: TCard, numericPresentation?: CardNumericPresentationContext): string;
+/**
+ * Convert data to JSON format
+ */
+export declare function convertToJSON(data: Record<string, any>[]): string;
+/**
+ * Download data as a file
+ */
+export declare function downloadFile(content: string, fileName: string, contentType: string): void;
+/**
+ * Export data as CSV
+ */
+export declare function exportAsCSV(data: Record<string, any>[], fileName?: string): void;
+/**
+ * Export data as CSV with formatting
+ */
+export declare function exportAsCSVWithFormatting(data: Record<string, any>[], columnSettings: ColumnSettingsMap, visibleColumns: string[], fileName?: string, contextTimezone?: string, browserTimezone?: string, isSqlCard?: boolean, card?: TCard, numericPresentation?: CardNumericPresentationContext): void;
+/**
+ * Export data as JSON
+ */
+export declare function exportAsJSON(data: Record<string, any>[], fileName?: string): void;