@tsingroc/tsingroc-components 5.0.2 → 5.1.0

package/dist/utils/accessibility.js

@@ -0,0 +1,214 @@
+import { c as _c } from "react/compiler-runtime";
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Accessibility utility functions and helpers
+ */
+
+/**
+ * Generate a unique ID for accessibility attributes
+ */
+export function generateAriaId(prefix) {
+  return `${prefix}-${Math.random().toString(36).substr(2, 9)}`;
+}
+
+/**
+ * Common ARIA labels for UI elements
+ */
+export const ARIA_LABELS = {
+  CLOSE: "关闭",
+  OPEN: "打开",
+  MENU: "菜单",
+  SEARCH: "搜索",
+  FILTER: "筛选",
+  EXPORT: "导出",
+  IMPORT: "导入",
+  SAVE: "保存",
+  CANCEL: "取消",
+  CONFIRM: "确认",
+  DELETE: "删除",
+  EDIT: "编辑",
+  ADD: "添加",
+  REMOVE: "移除",
+  REFRESH: "刷新",
+  LOAD_MORE: "加载更多",
+  PREVIOUS_PAGE: "上一页",
+  NEXT_PAGE: "下一页",
+  FIRST_PAGE: "首页",
+  LAST_PAGE: "末页",
+  LOADING: "加载中",
+  SUCCESS: "成功",
+  ERROR: "错误",
+  WARNING: "警告",
+  INFO: "信息"
+};
+
+/**
+ * ARIA roles for common UI patterns
+ */
+export const ARIA_ROLES = {
+  BUTTON: "button",
+  LINK: "link",
+  MENU: "menu",
+  MENUITEM: "menuitem",
+  TAB: "tab",
+  TABPANEL: "tabpanel",
+  TABLIST: "tablist",
+  DIALOG: "dialog",
+  ALERT: "alert",
+  ALERTDIALOG: "alertdialog",
+  STATUS: "status",
+  PROGRESSBAR: "progressbar",
+  SPINBUTTON: "spinbutton",
+  COMBOBOX: "combobox",
+  LISTBOX: "listbox",
+  OPTION: "option",
+  SEARCH: "search",
+  NAVIGATION: "navigation",
+  BANNER: "banner",
+  MAIN: "main",
+  COMPLEMENTARY: "complementary",
+  CONTENTINFO: "contentinfo"
+};
+
+/**
+ * Accessible button props generator
+ */
+export function getAccessibleButtonProps(label, props) {
+  return {
+    "aria-label": label,
+    role: ARIA_ROLES.BUTTON,
+    ...props
+  };
+}
+
+/**
+ * Accessible input props generator
+ */
+export function getAccessibleInputProps(label, props) {
+  return {
+    "aria-label": label,
+    ...props
+  };
+}
+
+/**
+ * Generate screen reader only text
+ */
+export function ScreenReaderOnly(t0) {
+  const $ = _c(3);
+  const {
+    children
+  } = t0;
+  let t1;
+  if ($[0] === Symbol.for("react.memo_cache_sentinel")) {
+    t1 = {
+      position: "absolute",
+      width: "1px",
+      height: "1px",
+      padding: 0,
+      margin: "-1px",
+      overflow: "hidden",
+      clip: "rect(0, 0, 0, 0)",
+      whiteSpace: "nowrap",
+      border: 0
+    };
+    $[0] = t1;
+  } else {
+    t1 = $[0];
+  }
+  let t2;
+  if ($[1] !== children) {
+    t2 = /*#__PURE__*/_jsx("span", {
+      style: t1,
+      children: children
+    });
+    $[1] = children;
+    $[2] = t2;
+  } else {
+    t2 = $[2];
+  }
+  return t2;
+}
+
+/**
+ * Keyboard event handler helpers
+ */
+export const keyboard = {
+  /** Check if Enter or Space key was pressed */
+  isActivationKey: event => event.key === "Enter" || event.key === " " || event.key === "Spacebar",
+  /** Check if Escape key was pressed */
+  isEscapeKey: event => event.key === "Escape",
+  /** Check if Arrow keys were pressed */
+  isArrowKey: event => event.key.startsWith("Arrow"),
+  /** Check if Tab key was pressed */
+  isTabKey: event => event.key === "Tab"
+};
+
+/**
+ * Focus management utilities
+ */
+export const focus = {
+  /** Trap focus within an element */
+  trapFocus: element => {
+    const focusableElements = element.querySelectorAll("a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex=\"-1\"])");
+    const firstFocusable = focusableElements[0];
+    const lastFocusable = focusableElements[focusableElements.length - 1];
+    const handleKeyDown = event => {
+      if (keyboard.isTabKey(event)) {
+        if (event.shiftKey) {
+          if (document.activeElement === firstFocusable) {
+            event.preventDefault();
+            lastFocusable?.focus();
+          }
+        } else {
+          if (document.activeElement === lastFocusable) {
+            event.preventDefault();
+            firstFocusable?.focus();
+          }
+        }
+      }
+    };
+    element.addEventListener("keydown", handleKeyDown);
+    firstFocusable?.focus();
+    return () => {
+      element.removeEventListener("keydown", handleKeyDown);
+    };
+  },
+  /** Restore focus to previous element */
+  restoreFocus: previousElement => {
+    if (previousElement) {
+      previousElement.focus();
+    }
+  }
+};
+
+/**
+ * Live region announcer for screen readers
+ */
+export function announceToScreenReader(message, priority = "polite") {
+  const announcement = document.createElement("div");
+  announcement.setAttribute("aria-live", priority);
+  announcement.setAttribute("aria-atomic", "true");
+  announcement.setAttribute("role", "status");
+  Object.assign(announcement.style, {
+    position: "absolute",
+    left: "-10000px",
+    width: "1px",
+    height: "1px",
+    overflow: "hidden"
+  });
+  document.body.appendChild(announcement);
+  announcement.textContent = message;
+  setTimeout(() => {
+    document.body.removeChild(announcement);
+  }, 1000);
+}
+
+/**
+ * Get accessible color contrast (WCAG compliance)
+ */
+export function getAccessibleColor(_bg, _fg, _level = "AA") {
+  // Simplified contrast check - in production, use a proper library
+  // This is a placeholder for the actual implementation
+  return true;
+}

package/dist/utils/constants.d.ts

@@ -0,0 +1,18 @@
+export declare const COLOR_PRICE_DAY_AHEAD = "#3773FF";
+export declare const COLOR_PRICE_REALTIME = "#FF5900";
+export declare const COLOR_POWER_GENERATION = "#8F59FA";
+export declare const COLOR_POWER_TSINGROC = "#85008C";
+export declare const COLOR_POWER_MANUAL = "#FF5900";
+export declare const COLOR_SECONDARY_COLOR = "#FF5900";
+export declare const COLOR_PROFIT_TSINGROC = "#85008C";
+export declare const COLOR_PROFIT_MANUAL = "#FF5900";
+export declare const COLOR_CHART_AXIS = "#ADADAD";
+export declare const COLOR_CARD_BACKGROUND_TSINGROC = "#F5EAF6";
+export declare const COLOR_CARD_CONTENT_TSINGROC = "#85008C";
+export declare const COLOR_CARD_BACKGROUND_MANUAL = "#FFEFE8";
+export declare const COLOR_CARD_CONTENT_MANUAL = "#FF5900";
+export declare const COLOR_TABLE_HEADER = "#F2F0F7";
+export declare const COLOR_TABLE_HOVER = "#DCDEE0";
+export declare const COLOR_TABLE_CELL_TSINGROC = "#85008C";
+export declare const COLOR_TABLE_CELL_MANUAL = "#FF5900";
+export declare const COLOR_TABLE_CELL_TEXT = "#000000";

package/dist/utils/constants.js

@@ -0,0 +1,34 @@
+const PRIMARY_COLOR = "#85008C";
+const PRIMARY_COLOR_LIGHT = "#8F59FA";
+const PRIMARY_COLOR_LIGHTER = "#F5EAF6";
+const PRIMARY_COLOR_LIGHTEST = "#DCDEE0";
+const PRIMARY_COLOR_MOST_LIGHTEST = "#F2F0F7";
+const SECONDARY_COLOR = "#FF5900";
+const SECONDARY_COLOR_LIGHTEST = "#FFEFE8";
+const TERTIARY_COLOR = "#3773FF";
+// const TERTIARY_COLOR_LIGHT = "#1890ff";
+const GREY = "#ADADAD";
+
+// Chart colors
+export const COLOR_PRICE_DAY_AHEAD = TERTIARY_COLOR;
+export const COLOR_PRICE_REALTIME = SECONDARY_COLOR;
+export const COLOR_POWER_GENERATION = PRIMARY_COLOR_LIGHT;
+export const COLOR_POWER_TSINGROC = PRIMARY_COLOR;
+export const COLOR_POWER_MANUAL = SECONDARY_COLOR;
+export const COLOR_SECONDARY_COLOR = SECONDARY_COLOR;
+export const COLOR_PROFIT_TSINGROC = PRIMARY_COLOR;
+export const COLOR_PROFIT_MANUAL = SECONDARY_COLOR;
+export const COLOR_CHART_AXIS = GREY;
+
+// Card Color
+export const COLOR_CARD_BACKGROUND_TSINGROC = PRIMARY_COLOR_LIGHTER;
+export const COLOR_CARD_CONTENT_TSINGROC = PRIMARY_COLOR;
+export const COLOR_CARD_BACKGROUND_MANUAL = SECONDARY_COLOR_LIGHTEST;
+export const COLOR_CARD_CONTENT_MANUAL = SECONDARY_COLOR;
+
+// Table Colors
+export const COLOR_TABLE_HEADER = PRIMARY_COLOR_MOST_LIGHTEST;
+export const COLOR_TABLE_HOVER = PRIMARY_COLOR_LIGHTEST;
+export const COLOR_TABLE_CELL_TSINGROC = PRIMARY_COLOR;
+export const COLOR_TABLE_CELL_MANUAL = SECONDARY_COLOR;
+export const COLOR_TABLE_CELL_TEXT = "#000000";

package/dist/utils/export.d.ts

@@ -0,0 +1,10 @@
+import type { ExtendedReviewValue } from "../pages/DayAheadReviewPage/types/dayahead";
+/**
+ * 将日前复盘数据导出为 Excel。
+ * 创建包含基础数据、详细数据和统计信息工作表的工作簿。
+ *
+ * @param data - 要导出的复盘值数组
+ * @param tradingDay - 复盘的交易日
+ * @param filename - 可选的自定义文件名
+ */
+export declare function exportDayAheadReviewDataToExcel(data: ExtendedReviewValue[], tradingDay: string, filename?: string): void;

package/dist/utils/export.js

@@ -0,0 +1,72 @@
+import * as XLSX from "@e965/xlsx";
+import dayjs from "dayjs";
+import { formatPrice, formatProfit, formatTime as formatReviewTime, formatVolume as formatReviewVolume } from "./formatters";
+
+/**
+ * 将日前复盘数据导出为 Excel。
+ * 创建包含基础数据、详细数据和统计信息工作表的工作簿。
+ *
+ * @param data - 要导出的复盘值数组
+ * @param tradingDay - 复盘的交易日
+ * @param filename - 可选的自定义文件名
+ */
+export function exportDayAheadReviewDataToExcel(data, tradingDay, filename) {
+  const basicWorksheetData = [["时段", "预测电量 (MWh)", "实际电量 (MWh)", "申报电量（智能体） (MWh)", "申报电量（人工） (MWh)", "日前价格 (¥/MWh)", "实时价格 (¥/MWh)"], ...data.map(item => [formatReviewTime(item.time), formatReviewVolume(item.forecastVolume), formatReviewVolume(item.actualVolume), formatReviewVolume(item.agentDeclaredVolume), formatReviewVolume(item.manualDeclaredVolume || 0), formatPrice(item.dayAheadPrice), formatPrice(item.realTimePrice)])];
+  const workbook = XLSX.utils.book_new();
+  const basicWorksheet = XLSX.utils.aoa_to_sheet(basicWorksheetData);
+  basicWorksheet["!cols"] = [{
+    width: 15
+  }, {
+    width: 18
+  }, {
+    width: 18
+  }, {
+    width: 22
+  }, {
+    width: 22
+  }, {
+    width: 18
+  }, {
+    width: 18
+  }];
+  XLSX.utils.book_append_sheet(workbook, basicWorksheet, "基础数据");
+  const detailedWorksheetData = [["时段", "预测电量 (MWh)", "实际电量 (MWh)", "申报电量（智能体） (MWh)", "申报电量（人工） (MWh)", "日前价格 (¥/MWh)", "实时价格 (¥/MWh)", "收益（智能体） (¥)", "收益（人工） (¥)"], ...data.map(item => [formatReviewTime(item.time), formatReviewVolume(item.forecastVolume), formatReviewVolume(item.actualVolume), formatReviewVolume(item.agentDeclaredVolume), formatReviewVolume(item.manualDeclaredVolume), formatPrice(item.dayAheadPrice), formatPrice(item.realTimePrice), formatProfit(item.agentProfit), formatProfit(item.manualProfit)])];
+  const detailedWorksheet = XLSX.utils.aoa_to_sheet(detailedWorksheetData);
+  detailedWorksheet["!cols"] = [{
+    width: 15
+  }, {
+    width: 18
+  }, {
+    width: 18
+  }, {
+    width: 22
+  }, {
+    width: 22
+  }, {
+    width: 18
+  }, {
+    width: 18
+  }, {
+    width: 18
+  }, {
+    width: 18
+  }];
+  XLSX.utils.book_append_sheet(workbook, detailedWorksheet, "详细数据");
+  const totalAgentProfit = data.reduce((sum, item) => sum + (item.agentProfit || 0), 0);
+  const totalManualProfit = data.reduce((sum, item) => sum + (item.manualProfit || 0), 0);
+  const totalForecastVolume = data.reduce((sum, item) => sum + (item.forecastVolume || 0), 0);
+  const totalActualVolume = data.reduce((sum, item) => sum + (item.actualVolume || 0), 0);
+  const totalAgentDeclaredVolume = data.reduce((sum, item) => sum + (item.agentDeclaredVolume || 0), 0);
+  const totalManualDeclaredVolume = data.reduce((sum, item) => sum + (item.manualDeclaredVolume || 0), 0);
+  const summaryInfoData = [["复盘信息", ""], ["交易日", tradingDay], ["", ""], ["数据统计", ""], ["总记录数", data.length.toString()], ["总预测电量 (MWh)", totalForecastVolume.toFixed(3)], ["总实际电量 (MWh)", totalActualVolume.toFixed(3)], ["总申报电量（智能体） (MWh)", totalAgentDeclaredVolume.toFixed(3)], ["总申报电量（人工） (MWh)", totalManualDeclaredVolume.toFixed(3)], ["", ""], ["收益统计", ""], ["总收益（智能体） (¥)", totalAgentProfit.toFixed(2)], ["总收益（人工） (¥)", totalManualProfit.toFixed(2)], ["收益差异 (¥)", (totalAgentProfit - totalManualProfit).toFixed(2)]];
+  const summaryInfoSheet = XLSX.utils.aoa_to_sheet(summaryInfoData);
+  summaryInfoSheet["!cols"] = [{
+    width: 25
+  }, {
+    width: 30
+  }];
+  XLSX.utils.book_append_sheet(workbook, summaryInfoSheet, "统计信息");
+  const defaultFilename = `日前交易复盘_${tradingDay}_${dayjs().format("YYYY-MM-DD")}.xlsx`;
+  const finalFilename = filename || defaultFilename;
+  XLSX.writeFile(workbook, finalFilename);
+}

package/dist/utils/formatters.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Pure formatting functions for domain data.
+ *
+ * DESIGN PRINCIPLES:
+ * - 0 is a VALID value (e.g., "no electricity traded") and should be formatted
+ * - null/undefined means "no data" - return null/undefined (let components decide presentation)
+ * - Formatters are pure functions - they don't handle UI presentation
+ *
+ * Presentation logic (how to show null) is handled by components/ui.
+ */
+export { presentCardValue } from "./ui";
+/**
+ * Format time string to readable Chinese format.
+ * Returns null for null/undefined input.
+ */
+export declare function formatTime(timeString: string | null | undefined): string | null;
+/**
+ * Format numeric value with specified decimal places.
+ * Always shows 0 as "0.00", "0.000", etc.
+ * Returns null for null/undefined input (components decide presentation).
+ *
+ * @param value - The number to format
+ * @param fractionDigits - Number of decimal places (default: 2)
+ * @returns Formatted string or null
+ */
+export declare function formatNumber(value: number | null | undefined, fractionDigits?: number): string | null;
+/**
+ * Format price value to 2 decimal places.
+ * Uses formatNumber internally - always shows 0 as "0.00".
+ */
+export declare function formatPrice(price: number | null | undefined): string | null;
+/**
+ * Format volume value to 3 decimal places.
+ * Uses formatNumber internally - always shows 0 as "0.000".
+ */
+export declare function formatVolume(volume: number | null | undefined): string | null;
+/**
+ * Format profit value to 2 decimal places.
+ * Uses formatNumber internally - always shows 0 as "0.00".
+ */
+export declare function formatProfit(profit: number | null | undefined): string | null;
+/**
+ * Format trade direction to Chinese.
+ * Returns null for null/undefined/empty input.
+ */
+export declare function formatDirection(direction: string | null | undefined): string | null;

package/dist/utils/formatters.js

@@ -0,0 +1,84 @@
+/**
+ * Pure formatting functions for domain data.
+ *
+ * DESIGN PRINCIPLES:
+ * - 0 is a VALID value (e.g., "no electricity traded") and should be formatted
+ * - null/undefined means "no data" - return null/undefined (let components decide presentation)
+ * - Formatters are pure functions - they don't handle UI presentation
+ *
+ * Presentation logic (how to show null) is handled by components/ui.
+ */
+
+// Re-export presentCardValue from ui for convenience
+export { presentCardValue } from "./ui";
+
+/**
+ * Format time string to readable Chinese format.
+ * Returns null for null/undefined input.
+ */
+export function formatTime(timeString) {
+  if (!timeString) return null;
+  const date = new Date(timeString);
+  if (Number.isNaN(date.valueOf())) return null;
+  return date.toLocaleString("zh-CN", {
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit"
+  });
+}
+
+/**
+ * Format numeric value with specified decimal places.
+ * Always shows 0 as "0.00", "0.000", etc.
+ * Returns null for null/undefined input (components decide presentation).
+ *
+ * @param value - The number to format
+ * @param fractionDigits - Number of decimal places (default: 2)
+ * @returns Formatted string or null
+ */
+export function formatNumber(value, fractionDigits = 2) {
+  if (value === null || value === undefined) return null;
+  return value.toFixed(fractionDigits);
+}
+
+/**
+ * Format price value to 2 decimal places.
+ * Uses formatNumber internally - always shows 0 as "0.00".
+ */
+export function formatPrice(price) {
+  return formatNumber(price, 2);
+}
+
+/**
+ * Format volume value to 3 decimal places.
+ * Uses formatNumber internally - always shows 0 as "0.000".
+ */
+export function formatVolume(volume) {
+  return formatNumber(volume, 3);
+}
+
+/**
+ * Format profit value to 2 decimal places.
+ * Uses formatNumber internally - always shows 0 as "0.00".
+ */
+export function formatProfit(profit) {
+  return formatNumber(profit, 2);
+}
+
+/**
+ * Format trade direction to Chinese.
+ * Returns null for null/undefined/empty input.
+ */
+export function formatDirection(direction) {
+  if (!direction) return null;
+  const directionMap = {
+    buy: "买入",
+    sell: "卖出",
+    买入: "买入",
+    卖出: "卖出"
+  };
+  return directionMap[direction] || direction;
+}

package/dist/utils/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./debug";
 export * from "./destructureLineDataItem";
+export * from "./export";
 export * from "./filterMap";
 export * from "./math";
 export * from "./mock";

package/dist/utils/index.js

@@ -1,5 +1,6 @@
 export * from "./debug";
 export * from "./destructureLineDataItem";
+export * from "./export";
 export * from "./filterMap";
 export * from "./math";
 export * from "./mock";

package/dist/utils/presenters.d.ts

@@ -0,0 +1,24 @@
+import type { Dayjs } from "dayjs";
+import type { ExtendedReviewValue, ProfitPlotValue } from "../pages/DayAheadReviewPage/types/dayahead";
+/**
+ * Returns true when any row has manual data (non-null manual fields).
+ * Used to show AI/manual mode selector: when manual fields are null, it's AI-only mode.
+ */
+export declare function hasManualData(tableData: ExtendedReviewValue[]): boolean;
+export declare function extractProfitData(tableData: ExtendedReviewValue[]): {
+    agentProfit: ProfitPlotValue[];
+    manualProfit: ProfitPlotValue[];
+};
+/**
+ * Hook for day-ahead trading days functionality.
+ * This is a simplified version that needs to be integrated with your TradingDayContext.
+ *
+ * @example
+ * ```tsx
+ * // In your component:
+ * const { disabledDate } = useDayAheadTradingDays();
+ * ```
+ */
+export declare function useDayAheadTradingDays(): {
+    disabledDate: (current: Dayjs | null) => boolean;
+};

package/dist/utils/presenters.js

@@ -0,0 +1,48 @@
+import dayjs from "dayjs";
+/**
+ * Returns true when any row has manual data (non-null manual fields).
+ * Used to show AI/manual mode selector: when manual fields are null, it's AI-only mode.
+ */
+export function hasManualData(tableData) {
+  return tableData.some(item => item.manualDeclaredVolume != null || item.manualDeclaredPrice != null || item.manualClearanceVolume != null || item.manualProfit != null);
+}
+export function extractProfitData(tableData) {
+  const agentProfit = tableData.map(item => ({
+    time: item.time,
+    agentProfit: item.agentProfit ?? 0,
+    agentPredictBaseline: item.agentPredictBaseline ?? 0,
+    agentStrategyAdd: item.agentStrategyAdd ?? 0
+  }));
+  const manualProfit = tableData.map(item => ({
+    time: item.time,
+    manualProfit: item.manualProfit ?? 0,
+    agentProfit: 0
+  }));
+  return {
+    agentProfit,
+    manualProfit
+  };
+}
+
+/**
+ * Hook for day-ahead trading days functionality.
+ * This is a simplified version that needs to be integrated with your TradingDayContext.
+ *
+ * @example
+ * ```tsx
+ * // In your component:
+ * const { disabledDate } = useDayAheadTradingDays();
+ * ```
+ */
+export function useDayAheadTradingDays() {
+  // This is a placeholder - in the actual implementation, this should
+  // connect to your TradingDayContext or similar state management
+  // For now, it returns a default implementation
+  return {
+    disabledDate: current => {
+      if (!current) return true;
+      // Disable future dates by default
+      return current.isAfter(dayjs(), "day");
+    }
+  };
+}

package/dist/utils/ui.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Presentation utilities for consistent null/undefined handling in components.
+ *
+ * These utilities handle how null/undefined values are displayed in the UI.
+ * Use these in components to apply consistent design tokens for missing data.
+ *
+ * @example
+ * ```tsx
+ * import { presentCardValue, presentTableValue } from './ui';
+ * import { formatPrice, formatVolume } from './formatters';
+ *
+ * // In a card (shows "-" for null)
+ * <Statistic title="Price" value={presentCardValue(formatPrice(data.price))} />
+ *
+ * // In a table (shows "" for null)
+ * <Table.Column render={() => presentTableValue(formatVolume(data.volume))} />
+ * ```
+ */
+/**
+ * Presentation options for null/undefined values.
+ */
+export type NullPresentation = "empty" | "dash" | "nbsp" | "na" | "zero";
+/**
+ * Default null presentation for different contexts.
+ */
+export declare const NULL_PRESENTATION_DEFAULTS: {
+    /** Default for tables: show empty string */
+    readonly table: "empty";
+    /** Default for cards: show dash */
+    readonly card: "dash";
+    /** Default for charts: show dash */
+    readonly chart: "dash";
+    /** Default for form inputs: show empty */
+    readonly form: "empty";
+};
+/**
+ * Present a nullable value with consistent null handling.
+ *
+ * This is the core presenter function that handles how null/undefined values
+ * are displayed in the UI. Use the convenience wrappers (presentCardValue,
+ * presentTableValue) for common cases.
+ *
+ * @param value - The formatted value (could be null from formatters)
+ * @param options - How to present null values
+ * @returns Display string
+ *
+ * @example
+ * ```tsx
+ * // Custom presentation
+ * <span>{presentValue(formatPrice(price), { nullAs: "na" })}</span>
+ *
+ * // Show N/A for null values
+ * <span>{presentValue(formatVolume(volume), { nullAs: "na" })}</span>
+ *
+ * // Use non-breaking space to prevent layout shift
+ * <span>{presentValue(formatProfit(profit), { nullAs: "nbsp" })}</span>
+ * ```
+ */
+export declare function presentValue(value: string | number | null | undefined, options?: {
+    /** How to present null/undefined (default: "empty") */
+    nullAs?: NullPresentation;
+    /** Optional fallback for zero values (default: show zero) */
+    zeroAs?: NullPresentation;
+}): string;
+/**
+ * Convenience presenter for card values (shows "-" for null).
+ *
+ * Use this in cards, statistics, and other UI elements where a dash "-".
+ *
+ * @example
+ * ```tsx
+ * import { presentCardValue } from './ui';
+ * import { formatPrice } from './formatters';
+ *
+ * <Statistic
+ *   title="Current Price"
+ *   value={presentCardValue(formatPrice(data.price))}
+ * />
+ * // null → "-", 0 → "0.00", 123.45 → "123.45"
+ * ```
+ */
+export declare function presentCardValue(value: string | number | null | undefined): string;
+/**
+ * Convenience presenter for table cells (shows "" for null).
+ *
+ * Use this in table cells and other compact UI elements where an empty string.
+ *
+ * @example
+ * ```tsx
+ * import { presentTableValue } from './ui';
+ * import { formatVolume } from './formatters';
+ *
+ * <Table.Column
+ *   render={(_, record) => presentTableValue(formatVolume(record.volume))}
+ * />
+ * // null → "", 0 → "0.000", 123.456 → "123.456"
+ * ```
+ */
+export declare function presentTableValue(value: string | number | null | undefined): string;
+/**
+ * Convenience presenter for chart tooltips (shows "-" for null).
+ *
+ * Use this in chart tooltips, legends, and other data visualizations.
+ *
+ * @example
+ * ```tsx
+ * import { presentChartValue } from './ui';
+ * import { formatProfit } from './formatters';
+ *
+ * tooltip: {
+ *   formatter: (params) => presentChartValue(formatProfit(params.value))
+ * }
+ * // null → "-", 0 → "0.00", 123.45 → "123.45"
+ * ```
+ */
+export declare function presentChartValue(value: string | number | null | undefined): string;