react-semaphor 0.1.183 → 0.1.185

package/dist/surfboard/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("../chunks/index-CcVMCdNu.js"),r=require("../types/index.cjs");exports.Surfboard=e.DashboardPlus;exports.EMPTY_SELECTION=r.EMPTY_SELECTION;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("../chunks/index-DnzN4EJh.js"),r=require("../chunks/common-types-CfJLrTJd.js"),a=require("../chunks/calendar-preferences-dialog-BlkO2Iyl.js");exports.Surfboard=e.DashboardPlus;exports.EMPTY_SELECTION=r.EMPTY_SELECTION;exports.CalendarPreferencesDialog=a.CalendarPreferencesDialog;

package/dist/surfboard/index.js

@@ -1,6 +1,8 @@
-import { a } from "../chunks/index-LgltNjBB.js";
-import { EMPTY_SELECTION as E } from "../types/index.js";
+import { a as e } from "../chunks/index-CWTYAZIx.js";
+import { E as f } from "../chunks/common-types-DhqlRVrq.js";
+import { C as E } from "../chunks/calendar-preferences-dialog-Cf45Z1iV.js";
 export {
-  E as EMPTY_SELECTION,
-  a as Surfboard
+  E as CalendarPreferencesDialog,
+  f as EMPTY_SELECTION,
+  e as Surfboard
 };

package/dist/types/dashboard.d.ts

@@ -128,6 +128,9 @@ declare interface CardConfig {
     metricColumns?: MetricField[];
     pivotByColumns?: PivotByField[];
     sortByColumns?: SortByField[];
+    detailColumns?: DetailField[];
+    /** Preserves non-detail config when switching to detail tables. */
+    detailTableBackup?: DetailTableBackupConfig;
     filters?: FilterGroup;
     joinPlan?: JoinPlan;
     rowLimit?: number;
@@ -398,7 +401,7 @@ declare interface DataSource {
     selectedEntities: SelectedEntities;
 }
 
-declare const DATE_FORMAT_VALUES: readonly ["MM-DD-YYYY", "YYYY-MM-DD", "MM/DD/YYYY", "DD/MM/YYYY", "MMMM DD, YYYY", "MMM DD, YYYY", "DD MMM YYYY", "Week of MMM DD, YYYY", "Week of MMMM DD, YYYY", "YYYY-WW", "MMM YYYY", "MMMM YYYY", "YYYY-MM", "MM/YYYY", "YYYY MMM", "Q1 YYYY", "YYYY Q1", "1st Quarter YYYY", "YYYY-Q1", "Quarter 1, YYYY", "YYYY", "YY", "custom"];
+declare const DATE_FORMAT_VALUES: readonly ["MM-DD-YYYY", "YYYY-MM-DD", "MM/DD/YYYY", "DD/MM/YYYY", "MMMM DD, YYYY", "MMM DD, YYYY", "DD MMM YYYY", "YYYY-MM-DD HH:mm", "YYYY-MM-DD HH:mm:ss", "YYYY-MM-DD HH:mm Z", "YYYY-MM-DD HH:mm:ss Z", "Week of MMM DD, YYYY", "Week of MMMM DD, YYYY", "YYYY-WW", "MMM YYYY", "MMMM YYYY", "YYYY-MM", "MM/YYYY", "YYYY MMM", "Q1 YYYY", "YYYY Q1", "1st Quarter YYYY", "YYYY-Q1", "Quarter 1, YYYY", "YYYY", "YY", "custom"];
 
 declare type DateFormatValue = (typeof DATE_FORMAT_VALUES)[number];
 
@@ -412,6 +415,35 @@ declare type DateSelectionMode = 'range' | 'months';
 
 declare type DateUnit = 'day' | 'week' | 'month' | 'quarter' | 'year';
 
+/**
+ * Field configuration for detail table columns.
+ * Unlike GroupByField, DetailField does not support aggregation or granularity.
+ * Columns are selected and displayed as-is from the database.
+ */
+declare interface DetailField extends Omit<Field, 'role' | 'granularity'> {
+    role: 'detail';
+    dateFormat?: DateFormatValue;
+    customFormat?: string;
+}
+
+declare interface DetailTableBackupConfig {
+    groupByColumns?: GroupByField[];
+    metricColumns?: MetricField[];
+    pivotByColumns?: PivotByField[];
+    sortByColumns?: SortByField[];
+    rowAggregates?: Array<{
+        label?: string;
+        function: AggregateFunction;
+        groupLevel: string | 'ALL';
+    }>;
+    columnAggregates?: Array<{
+        label?: string;
+        function: AggregateFunction;
+        pivotLevel: string | 'ALL';
+    }>;
+    comparisonType?: 'none' | 'previous_period' | 'same_period_last_year' | 'target' | 'start_vs_end';
+}
+
 declare type Dialect = 'mysql' | 'postgres' | 'bigquery' | 'redshift' | 'snowflake' | 'clickhouse' | 'duckdb' | 'mssql';
 
 export declare type DisplayDataType = 'string' | 'date' | 'number' | 'html' | 'none';
@@ -610,7 +642,7 @@ declare interface Field {
     entityId: string;
     entityName: string;
     entityType: EntityType;
-    role?: 'groupby' | 'metric' | 'sortby' | 'pivotby';
+    role?: 'groupby' | 'metric' | 'sortby' | 'pivotby' | 'detail';
 }
 
 declare type FileAttachment = {
@@ -1421,7 +1453,7 @@ export declare type TChartOptions = {
     treemapColorMode?: 'branch' | 'category';
 };
 
-declare type TChartType = 'bar' | 'horizontalBar' | 'line' | 'area' | 'stackedArea' | 'combo' | 'pie' | 'doughnut' | 'radar' | 'polarArea' | 'bubble' | 'scatter' | 'stackedBar' | 'stackedLine' | 'table' | 'pivotTable' | 'aggregateTable' | 'tableBuilder' | 'kpi' | 'pyramid' | 'tornado' | 'range' | 'text' | 'map' | 'funnel' | 'bullet' | 'heatmap' | 'treemap' | 'custom';
+declare type TChartType = 'bar' | 'horizontalBar' | 'line' | 'area' | 'stackedArea' | 'combo' | 'pie' | 'doughnut' | 'radar' | 'polarArea' | 'bubble' | 'scatter' | 'stackedBar' | 'stackedLine' | 'table' | 'pivotTable' | 'aggregateTable' | 'detailTable' | 'tableBuilder' | 'kpi' | 'pyramid' | 'tornado' | 'range' | 'text' | 'map' | 'funnel' | 'bullet' | 'heatmap' | 'treemap' | 'custom';
 
 export declare type TColumnSetting<T extends DisplayDataType> = {
     columnIdx: number;

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

@@ -114,8 +114,12 @@ export declare function escapeCSVValue(value: string | number | null | undefined
 export declare interface ExportFormattingConfig {
     /** Whether to apply formatting or export raw values */
     useFormattedValues: boolean;
-    /** User's timezone for date formatting (REQUIRED for Lambda) */
+    /** Context timezone for date formatting (calendarContext) */
     timezone: string;
+    /** Viewer/browser timezone for SQL card defaults */
+    browserTimezone?: string;
+    /** Whether the export is for a raw SQL card */
+    isSqlCard?: boolean;
     /** Locale for number/date formatting */
     locale: string;
     /** CSV delimiter */
@@ -146,6 +150,8 @@ export declare function formatCellValue(value: unknown, columnSettings: ColumnSe
     useFormattedValues: boolean;
     timezone: string;
     locale: string;
+    browserTimezone?: string;
+    isSqlCard?: boolean;
 }): string;
 
 /**
@@ -154,23 +160,24 @@ export declare function formatCellValue(value: unknown, columnSettings: ColumnSe
 export declare function formatCurrency(value: number | null | undefined, options?: NumberFormatOptions): string;
 
 /**
- * Format a date with explicit timezone
- * CRITICAL: Always use this in Lambda, never use plain format()
- */
-export declare function formatDate(value: string | Date | null | undefined, options?: DateFormatOptions, contextTimezone?: string): string;
-
-/**
- * Format a date value based on ColumnSettings.dateFormat
- * Used for export formatting
+ * Format a date with custom format and optional timezone
+ * This is the production implementation used by data-table and pivot-table.
+ *
+ * @param dateString - The date string to format
+ * @param formatPattern - The format pattern (e.g., 'MM/dd/yyyy', 'yyyy-MM-dd HH:mm')
+ *   Defaults to MM/dd/yyyy when missing or empty.
+ * @param displayTimezone - Optional timezone to display the date in (e.g., 'America/Chicago')
+ * @param sourceTimezone - How to interpret the input date (default: 'auto')
+ * @returns Formatted date string
+ *
+ * @example
+ * // Basic formatting
+ * formatDate('2024-01-15T10:30:00Z', 'MM/dd/yyyy') // '01/15/2024'
+ *
+ * // With display timezone
+ * formatDate('2024-01-15T10:30:00Z', 'MM/dd/yyyy HH:mm', 'America/Chicago') // '01/15/2024 04:30'
  */
-export declare function formatDateWithColumnSettings(value: string | Date | null | undefined, dateFormat: {
-    format?: string;
-    useCustomFormat?: boolean;
-    customFormat?: string;
-    useRelativeTime?: boolean;
-    timezone?: string;
-    sourceTimezone?: string;
-} | undefined, contextTimezone: string): string;
+export declare const formatDate: (dateString: string | null | undefined, formatPattern: string | undefined, displayTimezone?: string, sourceTimezone?: string) => string;
 
 /**
  * Format a number with locale-aware formatting
@@ -225,9 +232,13 @@ export declare function formatPivotDataRow(row: PivotRowData, pivotConfig: Pivot
 export declare function formatPivotTableForCSV(data: PivotRowData[], pivotConfig: PivotExportConfig, formattingConfig: ExportFormattingConfig): string[];
 
 /**
- * Format a date as relative time (e.g., "2 days ago")
+ * Format relative time using date-fns (e.g., "2 days ago")
+ *
+ * @param dateString - The date string to format
+ * @param sourceTimezone - How to interpret the input date (default: 'auto')
+ * @returns Relative time string
  */
-export declare function formatRelativeTime(value: string | Date | null | undefined): string;
+export declare const formatRelativeTime: (dateString: string | null | undefined, sourceTimezone?: string) => string;
 
 /**
  * Format a row of data for export
@@ -319,7 +330,7 @@ export declare function objectsToCSV(data: Record<string, unknown>[], options?:
  * @param sourceTimezone - How to interpret the date:
  *   - 'auto': If date has Z/offset, use it; otherwise assume UTC
  *   - 'UTC': Always interpret as UTC
- *   - specific TZ: Use explicit timezone if present, otherwise assume UTC
+ *   - specific TZ: Use explicit timezone if present, otherwise assume source TZ
  */
 export declare function parseWithSourceTimezone(dateString: string, sourceTimezone?: string): Date;
 
@@ -360,6 +371,18 @@ export declare interface PivotRowData {
     isGrandTotal?: boolean;
 }
 
+/**
+ * Date formatting utilities with timezone support
+ * IMPORTANT: No React imports allowed in this file
+ *
+ * Uses date-fns and date-fns-tz for consistent behavior in browser and Node.js
+ *
+ * This module provides the canonical date formatting functions used by:
+ * - data-table component
+ * - pivot-table component
+ * - aggregated-table component
+ * - Lambda CSV export (chunk-processor)
+ */
 /**
  * Resolve which timezone to use for formatting
  * Priority: column-specific > context timezone

package/dist/types/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e={database:null,schema:null,table:null};exports.EMPTY_SELECTION=e;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const T=require("../chunks/common-types-CfJLrTJd.js"),e={tz:"UTC",weekStart:1,anchor:"now"};exports.EMPTY_SELECTION=T.EMPTY_SELECTION;exports.DEFAULT_CALENDAR_CONTEXT=e;

package/dist/types/index.js

@@ -1,8 +1,11 @@
-const l = {
-  database: null,
-  schema: null,
-  table: null
+import { E as T } from "../chunks/common-types-DhqlRVrq.js";
+const E = {
+  tz: "UTC",
+  weekStart: 1,
+  // Monday (ISO standard)
+  anchor: "now"
 };
 export {
-  l as EMPTY_SELECTION
+  E as DEFAULT_CALENDAR_CONTEXT,
+  T as EMPTY_SELECTION
 };

package/dist/types/main.d.ts

@@ -444,6 +444,42 @@ export declare interface CalculatedFieldFormula {
  */
 export declare type CalculatedFieldOperation = 'sum' | 'difference' | 'product' | 'ratio' | 'change' | 'percentage' | 'scale' | 'custom';
 
+/**
+ * Calendar context for timezone-aware date operations.
+ * Controls how dates are interpreted, grouped, and displayed.
+ */
+export declare type CalendarContext = {
+    /**
+     * IANA timezone identifier.
+     * @example 'America/Chicago', 'Europe/London', 'Asia/Tokyo', 'UTC'
+     * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
+     */
+    tz: string;
+    /**
+     * Day the week starts on.
+     * 0 = Sunday (US, Canada, Japan)
+     * 1 = Monday (ISO standard, most of Europe)
+     * 6 = Saturday (Middle East)
+     * @default 1 (Monday) for backward compatibility
+     */
+    weekStart: WeekStart;
+    /**
+     * Date anchor for relative date calculations.
+     * - 'now': Use current time (default, live dashboards)
+     * - { iso: string }: Fixed ISO 8601 date for reproducible views
+     */
+    anchor: 'now' | {
+        iso: string;
+    };
+};
+
+export declare function CalendarPreferencesDialog({ open, onOpenChange, }: CalendarPreferencesDialogProps): JSX.Element;
+
+declare interface CalendarPreferencesDialogProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+}
+
 /**
  * Cancel/delete an export job
  */
@@ -454,6 +490,9 @@ export declare interface CardConfig {
     metricColumns?: MetricField[];
     pivotByColumns?: PivotByField[];
     sortByColumns?: SortByField[];
+    detailColumns?: DetailField[];
+    /** Preserves non-detail config when switching to detail tables. */
+    detailTableBackup?: DetailTableBackupConfig;
     filters?: FilterGroup;
     joinPlan?: JoinPlan;
     rowLimit?: number;
@@ -508,7 +547,7 @@ export declare interface CardInteractionConfig {
 
 export declare type CardMode = 'explorer' | 'dev';
 
-export declare type CardType = 'table' | 'aggregateTable' | 'pivotTable';
+export declare type CardType = 'table' | 'aggregateTable' | 'pivotTable' | 'detailTable';
 
 declare type CardWithContent = BaseCustomCard & {
     content: React.FC<{
@@ -710,7 +749,7 @@ export declare type ConnectionPolicy = {
 
 export declare type ConnectionType = 'GoogleSheets' | 'MySQL' | 'MSSQL' | 'PostgreSQL' | 'BigQuery' | 'Redshift' | 'Snowflake' | 'S3' | 'clickhouse' | 'S3Tables' | 'API' | 'none';
 
-export declare type ContainerId = 'groupBy' | 'metrics' | 'pivotBy' | 'sortBy' | 'source';
+export declare type ContainerId = 'groupBy' | 'metrics' | 'pivotBy' | 'sortBy' | 'detailColumns' | 'source';
 
 /**
  * Factory function to create empty KPI card configuration
@@ -944,7 +983,7 @@ export declare interface DataSource {
 
 export declare type DataType = 'string' | 'number' | 'date' | 'datetime' | 'boolean' | 'json' | 'geo';
 
-export declare const DATE_FORMAT_VALUES: readonly ["MM-DD-YYYY", "YYYY-MM-DD", "MM/DD/YYYY", "DD/MM/YYYY", "MMMM DD, YYYY", "MMM DD, YYYY", "DD MMM YYYY", "Week of MMM DD, YYYY", "Week of MMMM DD, YYYY", "YYYY-WW", "MMM YYYY", "MMMM YYYY", "YYYY-MM", "MM/YYYY", "YYYY MMM", "Q1 YYYY", "YYYY Q1", "1st Quarter YYYY", "YYYY-Q1", "Quarter 1, YYYY", "YYYY", "YY", "custom"];
+export declare const DATE_FORMAT_VALUES: readonly ["MM-DD-YYYY", "YYYY-MM-DD", "MM/DD/YYYY", "DD/MM/YYYY", "MMMM DD, YYYY", "MMM DD, YYYY", "DD MMM YYYY", "YYYY-MM-DD HH:mm", "YYYY-MM-DD HH:mm:ss", "YYYY-MM-DD HH:mm Z", "YYYY-MM-DD HH:mm:ss Z", "Week of MMM DD, YYYY", "Week of MMMM DD, YYYY", "YYYY-WW", "MMM YYYY", "MMMM YYYY", "YYYY-MM", "MM/YYYY", "YYYY MMM", "Q1 YYYY", "YYYY Q1", "1st Quarter YYYY", "YYYY-Q1", "Quarter 1, YYYY", "YYYY", "YY", "custom"];
 
 export declare type DateFormatOption = {
     value: DateFormatValue;
@@ -965,6 +1004,41 @@ declare type DateSelectionMode = 'range' | 'months';
 
 declare type DateUnit = 'day' | 'week' | 'month' | 'quarter' | 'year';
 
+/**
+ * Default CalendarContext when not provided.
+ * Used as fallback for backward compatibility.
+ */
+export declare const DEFAULT_CALENDAR_CONTEXT: CalendarContext;
+
+/**
+ * Field configuration for detail table columns.
+ * Unlike GroupByField, DetailField does not support aggregation or granularity.
+ * Columns are selected and displayed as-is from the database.
+ */
+export declare interface DetailField extends Omit<Field, 'role' | 'granularity'> {
+    role: 'detail';
+    dateFormat?: DateFormatValue;
+    customFormat?: string;
+}
+
+export declare interface DetailTableBackupConfig {
+    groupByColumns?: GroupByField[];
+    metricColumns?: MetricField[];
+    pivotByColumns?: PivotByField[];
+    sortByColumns?: SortByField[];
+    rowAggregates?: Array<{
+        label?: string;
+        function: AggregateFunction;
+        groupLevel: string | 'ALL';
+    }>;
+    columnAggregates?: Array<{
+        label?: string;
+        function: AggregateFunction;
+        pivotLevel: string | 'ALL';
+    }>;
+    comparisonType?: 'none' | 'previous_period' | 'same_period_last_year' | 'target' | 'start_vs_end';
+}
+
 export declare type Dialect = 'mysql' | 'postgres' | 'bigquery' | 'redshift' | 'snowflake' | 'clickhouse' | 'duckdb' | 'mssql';
 
 export declare type DisplayDataType = 'string' | 'date' | 'number' | 'html' | 'none';
@@ -1385,6 +1459,8 @@ export declare type ExportFormat = 'csv';
 export declare interface ExportFormattingConfig {
     useFormattedValues: boolean;
     timezone: string;
+    browserTimezone?: string;
+    isSqlCard?: boolean;
     locale: string;
     delimiter: ',' | ';' | '\t';
     includeHeaders: boolean;
@@ -1509,7 +1585,7 @@ export declare interface Field {
     entityId: string;
     entityName: string;
     entityType: EntityType;
-    role?: 'groupby' | 'metric' | 'sortby' | 'pivotby';
+    role?: 'groupby' | 'metric' | 'sortby' | 'pivotby' | 'detail';
 }
 
 declare type FileAttachment = {
@@ -2163,6 +2239,22 @@ export declare interface QueryConfig {
     orderBy?: OrderBy[];
 }
 
+/**
+ * Response structure for query execution (standard queries and comparison queries)
+ */
+export declare interface QueryExecutionResponse {
+    records: any[];
+    output: string;
+    rowLimitExceeded: boolean;
+    sql?: string;
+    userSql?: string;
+    pivotSchema?: any;
+    pagination?: PaginationMetadata;
+    subtotalColumns?: string[];
+    columnSubtotalMeta?: any;
+    metadata?: any;
+}
+
 export declare type QueryFilter = {
     filterColumnName: string;
     filterValue: OldFilterValue;
@@ -2198,6 +2290,22 @@ export declare function resolveDatamodelName(datamodelName: string): string;
 
 export declare const resolveDataType: (value: any) => string;
 
+/**
+ * Parameters in JWT payload (after backend resolution).
+ * The backend ALWAYS includes calendarContext, even if customer didn't provide it.
+ */
+export declare type ResolvedTokenParams = Omit<TokenParams, 'calendarContext'> & {
+    /**
+     * Full calendar context for timezone-aware operations.
+     * ALWAYS present in JWT - resolved by backend from:
+     * 1. Token request calendarContext (highest priority)
+     * 2. Token request timezone (legacy)
+     * 3. User/Tenant/Org preferences (Phase 7)
+     * 4. Default: { tz: 'UTC', weekStart: 1, anchor: 'now' }
+     */
+    calendarContext: CalendarContext;
+};
+
 export declare interface ResourceListItem {
     id: string;
     title: string;
@@ -2705,7 +2813,7 @@ export declare type TChartOptions = {
     treemapColorMode?: 'branch' | 'category';
 };
 
-declare type TChartType = 'bar' | 'horizontalBar' | 'line' | 'area' | 'stackedArea' | 'combo' | 'pie' | 'doughnut' | 'radar' | 'polarArea' | 'bubble' | 'scatter' | 'stackedBar' | 'stackedLine' | 'table' | 'pivotTable' | 'aggregateTable' | 'tableBuilder' | 'kpi' | 'pyramid' | 'tornado' | 'range' | 'text' | 'map' | 'funnel' | 'bullet' | 'heatmap' | 'treemap' | 'custom';
+declare type TChartType = 'bar' | 'horizontalBar' | 'line' | 'area' | 'stackedArea' | 'combo' | 'pie' | 'doughnut' | 'radar' | 'polarArea' | 'bubble' | 'scatter' | 'stackedBar' | 'stackedLine' | 'table' | 'pivotTable' | 'aggregateTable' | 'detailTable' | 'tableBuilder' | 'kpi' | 'pyramid' | 'tornado' | 'range' | 'text' | 'map' | 'funnel' | 'bullet' | 'heatmap' | 'treemap' | 'custom';
 
 export declare type TColumnSetting<T extends DisplayDataType> = {
     columnIdx: number;
@@ -3028,8 +3136,12 @@ export declare type TLineStyle = 'solid' | 'dashed' | 'dotted' | 'dash-dot';
 
 /**
  * Parameters for customizing token behavior and formatting.
+ * This is used for token REQUEST (customer provides these).
  */
 export declare type TokenParams = {
+    /**
+     * Currency formatting options.
+     */
     currencyFormat?: {
         /**
          * Locale identifier (e.g., 'en-US', 'fr-FR').
@@ -3041,11 +3153,23 @@ export declare type TokenParams = {
         currency: string;
     };
     /**
-     * Time zone identifier (e.g., 'America/New_York', 'Europe/London').
+     * IANA timezone identifier for date operations.
+     * @deprecated Use calendarContext.tz instead for full calendar control.
+     * @example 'America/Chicago', 'Europe/London'
      */
     timezone?: string;
+    /**
+     * Full calendar context for timezone-aware operations.
+     * Optional in token request - the backend ALWAYS resolves and includes
+     * this in the JWT, even when the customer doesn't provide it.
+     */
+    calendarContext?: CalendarContext;
 };
 
+/**
+ * Token properties from JWT payload.
+ * This is what the frontend receives after token generation.
+ */
 export declare type TokenProps = {
     /**
      * Allowed semantic domains.
@@ -3107,8 +3231,9 @@ export declare type TokenProps = {
     rcls?: TokenSecurityPolicy[] | TokenSecurityPolicy;
     /**
      * Parameter overrides and preferences (e.g., formatting).
+     * Uses ResolvedTokenParams because backend ALWAYS includes calendarContext.
      */
-    params?: TokenParams;
+    params?: ResolvedTokenParams;
     /**
      * UI behavior and feature flags.
      */
@@ -3648,4 +3773,12 @@ declare type VisualProps = DashboardProps & {
     displayPreferences?: VisualDisplayPreferences;
 };
 
+/**
+ * Week start day type.
+ * 0 = Sunday (US, Canada, Japan)
+ * 1 = Monday (ISO standard, most of Europe)
+ * 6 = Saturday (Middle East)
+ */
+export declare type WeekStart = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+
 export { }

package/dist/types/surfboard.d.ts

@@ -123,11 +123,21 @@ declare interface CalculatedFieldFormula {
  */
 declare type CalculatedFieldOperation = 'sum' | 'difference' | 'product' | 'ratio' | 'change' | 'percentage' | 'scale' | 'custom';
 
+export declare function CalendarPreferencesDialog({ open, onOpenChange, }: CalendarPreferencesDialogProps): JSX.Element;
+
+declare interface CalendarPreferencesDialogProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+}
+
 declare interface CardConfig {
     groupByColumns?: GroupByField[];
     metricColumns?: MetricField[];
     pivotByColumns?: PivotByField[];
     sortByColumns?: SortByField[];
+    detailColumns?: DetailField[];
+    /** Preserves non-detail config when switching to detail tables. */
+    detailTableBackup?: DetailTableBackupConfig;
     filters?: FilterGroup;
     joinPlan?: JoinPlan;
     rowLimit?: number;
@@ -401,7 +411,7 @@ declare interface DataSource {
     selectedEntities: SelectedEntities;
 }
 
-declare const DATE_FORMAT_VALUES: readonly ["MM-DD-YYYY", "YYYY-MM-DD", "MM/DD/YYYY", "DD/MM/YYYY", "MMMM DD, YYYY", "MMM DD, YYYY", "DD MMM YYYY", "Week of MMM DD, YYYY", "Week of MMMM DD, YYYY", "YYYY-WW", "MMM YYYY", "MMMM YYYY", "YYYY-MM", "MM/YYYY", "YYYY MMM", "Q1 YYYY", "YYYY Q1", "1st Quarter YYYY", "YYYY-Q1", "Quarter 1, YYYY", "YYYY", "YY", "custom"];
+declare const DATE_FORMAT_VALUES: readonly ["MM-DD-YYYY", "YYYY-MM-DD", "MM/DD/YYYY", "DD/MM/YYYY", "MMMM DD, YYYY", "MMM DD, YYYY", "DD MMM YYYY", "YYYY-MM-DD HH:mm", "YYYY-MM-DD HH:mm:ss", "YYYY-MM-DD HH:mm Z", "YYYY-MM-DD HH:mm:ss Z", "Week of MMM DD, YYYY", "Week of MMMM DD, YYYY", "YYYY-WW", "MMM YYYY", "MMMM YYYY", "YYYY-MM", "MM/YYYY", "YYYY MMM", "Q1 YYYY", "YYYY Q1", "1st Quarter YYYY", "YYYY-Q1", "Quarter 1, YYYY", "YYYY", "YY", "custom"];
 
 declare type DateFormatValue = (typeof DATE_FORMAT_VALUES)[number];
 
@@ -415,6 +425,35 @@ declare type DateSelectionMode = 'range' | 'months';
 
 declare type DateUnit = 'day' | 'week' | 'month' | 'quarter' | 'year';
 
+/**
+ * Field configuration for detail table columns.
+ * Unlike GroupByField, DetailField does not support aggregation or granularity.
+ * Columns are selected and displayed as-is from the database.
+ */
+declare interface DetailField extends Omit<Field, 'role' | 'granularity'> {
+    role: 'detail';
+    dateFormat?: DateFormatValue;
+    customFormat?: string;
+}
+
+declare interface DetailTableBackupConfig {
+    groupByColumns?: GroupByField[];
+    metricColumns?: MetricField[];
+    pivotByColumns?: PivotByField[];
+    sortByColumns?: SortByField[];
+    rowAggregates?: Array<{
+        label?: string;
+        function: AggregateFunction;
+        groupLevel: string | 'ALL';
+    }>;
+    columnAggregates?: Array<{
+        label?: string;
+        function: AggregateFunction;
+        pivotLevel: string | 'ALL';
+    }>;
+    comparisonType?: 'none' | 'previous_period' | 'same_period_last_year' | 'target' | 'start_vs_end';
+}
+
 declare type Dialect = 'mysql' | 'postgres' | 'bigquery' | 'redshift' | 'snowflake' | 'clickhouse' | 'duckdb' | 'mssql';
 
 export declare type DisplayDataType = 'string' | 'date' | 'number' | 'html' | 'none';
@@ -613,7 +652,7 @@ declare interface Field {
     entityId: string;
     entityName: string;
     entityType: EntityType;
-    role?: 'groupby' | 'metric' | 'sortby' | 'pivotby';
+    role?: 'groupby' | 'metric' | 'sortby' | 'pivotby' | 'detail';
 }
 
 declare type FileAttachment = {
@@ -1426,7 +1465,7 @@ export declare type TChartOptions = {
     treemapColorMode?: 'branch' | 'category';
 };
 
-declare type TChartType = 'bar' | 'horizontalBar' | 'line' | 'area' | 'stackedArea' | 'combo' | 'pie' | 'doughnut' | 'radar' | 'polarArea' | 'bubble' | 'scatter' | 'stackedBar' | 'stackedLine' | 'table' | 'pivotTable' | 'aggregateTable' | 'tableBuilder' | 'kpi' | 'pyramid' | 'tornado' | 'range' | 'text' | 'map' | 'funnel' | 'bullet' | 'heatmap' | 'treemap' | 'custom';
+declare type TChartType = 'bar' | 'horizontalBar' | 'line' | 'area' | 'stackedArea' | 'combo' | 'pie' | 'doughnut' | 'radar' | 'polarArea' | 'bubble' | 'scatter' | 'stackedBar' | 'stackedLine' | 'table' | 'pivotTable' | 'aggregateTable' | 'detailTable' | 'tableBuilder' | 'kpi' | 'pyramid' | 'tornado' | 'range' | 'text' | 'map' | 'funnel' | 'bullet' | 'heatmap' | 'treemap' | 'custom';
 
 export declare type TColumnSetting<T extends DisplayDataType> = {
     columnIdx: number;