react-semaphor 0.1.177 → 0.1.179

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

@@ -0,0 +1,375 @@
+export declare interface AggregateExportConfig {
+    groupByColumns: GroupByField[];
+    pivotSchema: PivotColumnSchema[];
+    rowAggregates?: RowAggregate[];
+    includeSubtotals: boolean;
+    includeGrandTotal: boolean;
+}
+
+export declare interface AggregateRowData extends Record<string, unknown> {
+    isSubtotal?: boolean;
+    isGrandTotal?: boolean;
+    subtotalLevel?: string;
+    subtotalContext?: {
+        groupByValues?: Record<string, unknown>;
+    };
+    aggregate?: string;
+}
+
+/**
+ * Convert a 2D array to CSV string
+ */
+export declare function arrayToCSV(rows: (string | number | null | undefined)[][], options?: Partial<CSVExportOptions>): string;
+
+/**
+ * Convert an array of values to a CSV row
+ */
+export declare function arrayToCSVRow(values: (string | number | null | undefined)[], delimiter?: string): string;
+
+export declare interface ColorRange {
+    min: number;
+    max: number;
+    color: string;
+    applyTo: 'cell' | 'row';
+}
+
+export declare interface ColumnHeaderNode {
+    name: string;
+    level: number;
+    colspan: number;
+    children?: ColumnHeaderNode[];
+    columnKey?: string;
+}
+
+export declare interface ColumnSettings {
+    type: 'none' | 'text' | 'number' | 'date' | 'badge' | 'link' | 'progress';
+    textAlign?: 'left' | 'center' | 'right';
+    width?: number;
+    numberFormat?: {
+        style: 'decimal' | 'currency' | 'percent';
+        currency: string;
+        locale: string;
+        minimumFractionDigits: number;
+        maximumFractionDigits: number;
+        showDataBar?: boolean;
+        dataBarColor?: string;
+        dataBarMinValue?: number;
+        dataBarMaxValue?: number;
+    };
+    dateFormat?: {
+        format: string;
+        useCustomFormat: boolean;
+        customFormat: string;
+        useRelativeTime: boolean;
+        timezone?: string;
+        sourceTimezone?: string;
+    };
+    linkFormat?: {
+        urlTemplate: string;
+        labelType: 'value' | 'static' | 'column';
+        staticLabel?: string;
+        labelColumn?: string;
+        openInNewTab: boolean;
+    };
+    colorRanges?: ColorRange[];
+}
+
+export declare type ColumnSettingsMap = Record<string, ColumnSettings>;
+
+export declare interface ColumnSubtotalMeta {
+    columnKey: string;
+    label: string;
+    level: number;
+}
+
+export declare interface CSVExportOptions {
+    delimiter: ',' | ';' | '\t';
+    includeHeaders: boolean;
+    lineEnding: '\n' | '\r\n';
+}
+
+export declare interface DateFormatOptions {
+    /** date-fns format pattern (e.g., "MM/dd/yyyy") */
+    format: string;
+    /** Use custom format instead of preset */
+    useCustomFormat?: boolean;
+    /** Custom format pattern */
+    customFormat?: string;
+    /** Display timezone (e.g., "America/New_York") */
+    timezone?: string;
+    /** How to interpret source dates: 'auto' | 'UTC' | specific timezone */
+    sourceTimezone?: string;
+    /** Use relative time (e.g., "2 days ago") */
+    useRelativeTime?: boolean;
+    /** Locale for date formatting */
+    locale?: string;
+}
+
+/**
+ * Escape a value for CSV output (RFC 4180 compliant)
+ * Wraps in quotes if value contains delimiter, quotes, or newlines
+ */
+export declare function escapeCSVValue(value: string | number | null | undefined, delimiter?: string): string;
+
+export declare interface ExportFormattingConfig {
+    /** Whether to apply formatting or export raw values */
+    useFormattedValues: boolean;
+    /** User's timezone for date formatting (REQUIRED for Lambda) */
+    timezone: string;
+    /** Locale for number/date formatting */
+    locale: string;
+    /** CSV delimiter */
+    delimiter: ',' | ';' | '\t';
+    /** Include header row */
+    includeHeaders: boolean;
+    /** Per-column formatting settings */
+    columnSettings: ColumnSettingsMap;
+    /** Ordered list of columns to include */
+    visibleColumns: string[];
+}
+
+/**
+ * Format an aggregate table row for CSV export
+ */
+export declare function formatAggregateRow(row: AggregateRowData, aggregateConfig: AggregateExportConfig, formattingConfig: ExportFormattingConfig): string[];
+
+/**
+ * Format aggregate table data for CSV export
+ */
+export declare function formatAggregateTableForCSV(data: AggregateRowData[], aggregateConfig: AggregateExportConfig, formattingConfig: ExportFormattingConfig): string[];
+
+/**
+ * Format a cell value for export based on column settings
+ * This is the main entry point for formatting individual cells
+ */
+export declare function formatCellValue(value: unknown, columnSettings: ColumnSettings | undefined, config: {
+    useFormattedValues: boolean;
+    timezone: string;
+    locale: string;
+}): string;
+
+/**
+ * Format a number as currency
+ */
+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
+ */
+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;
+
+/**
+ * Format a number with locale-aware formatting
+ */
+export declare function formatNumber(value: number | null | undefined, options?: NumberFormatOptions): string;
+
+/**
+ * Legacy wrapper for backward compatibility with existing code
+ * @deprecated Use formatNumber, formatCurrency, or formatPercent directly
+ */
+export declare function formatNumberCustom(value: number, type: 'number' | 'currency' | 'percent' | 'scientific', options?: FormatOptions): string;
+
+/**
+ * Format a number value based on ColumnSettings.numberFormat
+ * Used for export formatting
+ */
+export declare function formatNumberWithColumnSettings(value: number | null | undefined, numberFormat: {
+    style?: 'decimal' | 'currency' | 'percent';
+    currency?: string;
+    locale?: string;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+} | undefined, defaultLocale?: string): string;
+
+export declare interface FormatOptions {
+    decimalPlaces?: number;
+    useSuffix?: boolean;
+    currency?: string;
+    locale?: string;
+    prefix?: string;
+    suffix?: string;
+    negativeInParentheses?: boolean;
+    multiplyBy?: number;
+}
+
+/**
+ * Format a number as percentage
+ * Note: Intl.NumberFormat percent style multiplies by 100, so we may need to divide
+ */
+export declare function formatPercent(value: number | null | undefined, options?: NumberFormatOptions & {
+    alreadyPercent?: boolean;
+}): string;
+
+/**
+ * Format a pivot table data row for CSV export
+ */
+export declare function formatPivotDataRow(row: PivotRowData, pivotConfig: PivotExportConfig, formattingConfig: ExportFormattingConfig): string[];
+
+/**
+ * Format pivot table data for CSV export
+ */
+export declare function formatPivotTableForCSV(data: PivotRowData[], pivotConfig: PivotExportConfig, formattingConfig: ExportFormattingConfig): string[];
+
+/**
+ * Format a date as relative time (e.g., "2 days ago")
+ */
+export declare function formatRelativeTime(value: string | Date | null | undefined): string;
+
+/**
+ * Format a row of data for export
+ * Returns values in the order specified by visibleColumns
+ */
+export declare function formatRowForExport(row: Record<string, unknown>, config: ExportFormattingConfig): string[];
+
+/**
+ * Format a number in scientific notation
+ */
+export declare function formatScientific(value: number | null | undefined, options?: NumberFormatOptions): string;
+
+/**
+ * Format table data for CSV export
+ * Returns array of CSV rows (strings)
+ */
+export declare function formatTableForCSV(data: Record<string, unknown>[], config: ExportFormattingConfig): string[];
+
+/**
+ * Generate headers for aggregate table export
+ */
+export declare function generateAggregateHeaders(aggregateConfig: AggregateExportConfig): string[];
+
+/**
+ * Generate multi-level headers for pivot table
+ */
+export declare function generatePivotHeaders(config: PivotExportConfig): string[][];
+
+/**
+ * Generate complete CSV content for a table
+ */
+export declare function generateTableCSV(data: Record<string, unknown>[], config: ExportFormattingConfig, lineEnding?: '\n' | '\r\n'): string;
+
+/**
+ * Get timezone abbreviation (e.g., "EST", "PST")
+ */
+export declare function getTimezoneAbbreviation(timezone: string, date?: Date): string;
+
+/**
+ * Get friendly timezone name (e.g., "Eastern Time")
+ */
+export declare function getTimezoneName(timezone: string): string;
+
+export declare interface GroupByField {
+    name: string;
+    alias: string;
+    label?: string;
+}
+
+/**
+ * Shared format types for export system
+ * IMPORTANT: No React imports allowed in this file
+ *
+ * These types are used by:
+ * - react-semaphor (browser) for client-side exports
+ * - semaphor-app (Next.js) for API routes
+ * - Lambda (Node.js) for async export processing
+ */
+export declare interface NumberFormatOptions {
+    style: 'decimal' | 'currency' | 'percent';
+    locale?: string;
+    currency?: string;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    useGrouping?: boolean;
+    /** Multiply value before formatting (e.g., 100 for percent) */
+    multiplyBy?: number;
+    /** Add prefix string (e.g., "$") */
+    prefix?: string;
+    /** Add suffix string (e.g., " USD") */
+    suffix?: string;
+    /** Show negative numbers in parentheses instead of minus sign */
+    negativeInParentheses?: boolean;
+    /** Use magnitude suffixes (K, M, B) */
+    useSuffix?: boolean;
+}
+
+/**
+ * Convert an array of objects to CSV string
+ */
+export declare function objectsToCSV(data: Record<string, unknown>[], options?: Partial<CSVExportOptions> & {
+    columns?: string[];
+}): string;
+
+/**
+ * Parse a date string with source timezone interpretation
+ *
+ * @param dateString - The date string to parse
+ * @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
+ */
+export declare function parseWithSourceTimezone(dateString: string, sourceTimezone?: string): Date;
+
+export declare interface PivotByColumn {
+    name: string;
+    alias: string;
+    label?: string;
+}
+
+export declare interface PivotCellData {
+    value: unknown;
+    formatted?: string;
+}
+
+export declare interface PivotColumnSchema {
+    alias: string;
+    displayLabel?: string;
+    metricLabel?: string;
+    metricName?: string;
+    isMetricColumn: boolean;
+}
+
+export declare interface PivotExportConfig {
+    groupByColumns: GroupByField[];
+    pivotByColumns: PivotByColumn[];
+    columnHeadersTree: ColumnHeaderNode[];
+    columnHeaders: string[];
+    columnSubtotalMeta?: ColumnSubtotalMeta[];
+    includeSubtotals: boolean;
+    includeGrandTotal: boolean;
+    showRowTotals: boolean;
+}
+
+export declare interface PivotRowData {
+    fieldValues: string[];
+    cells: Record<string, PivotCellData>;
+    isSubtotal?: boolean;
+    isGrandTotal?: boolean;
+}
+
+/**
+ * Resolve which timezone to use for formatting
+ * Priority: column-specific > context timezone
+ */
+export declare function resolveTimezone(columnTimezone: string | undefined, contextTimezone: string): string;
+
+export declare interface RowAggregate {
+    function: 'SUM' | 'COUNT' | 'AVG' | 'MIN' | 'MAX';
+    groupLevel?: string;
+    label?: string;
+}
+
+export { }

package/package.json

@@ -5,7 +5,7 @@
     "email": "support@semaphor.cloud"
   },
   "license": "MIT",
-  "version": "0.1.177",
+  "version": "0.1.179",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",
@@ -37,6 +37,11 @@
       "import": "./dist/surfboard/index.js",
       "require": "./dist/surfboard/index.cjs"
     },
+    "./format-utils": {
+      "types": "./dist/types/format-utils.d.ts",
+      "import": "./dist/format-utils/index.js",
+      "require": "./dist/format-utils/index.cjs"
+    },
     "./style.css": "./dist/style.css"
   },
   "scripts": {
@@ -135,6 +140,14 @@
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
   "overrides": {
     "react": "$react",
     "react-dom": "$react-dom"