arthub-table 0.0.3

package/dist/types/core/viewers/types.d.ts

@@ -0,0 +1,1097 @@
+/**
+ * Canvas-Table Viewer Type System
+ * Data-driven cell viewer interfaces and types
+ */
+import type Paint from '../Paint';
+import type DataGrid from '../DataGrid';
+/**
+ * Bounds of a cell for rendering
+ */
+export interface CellBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Render context passed to viewers
+ */
+export interface ViewerRenderContext {
+    /** Canvas 2D rendering context */
+    ctx: CanvasRenderingContext2D;
+    /** Painter utility for drawing */
+    painter: Paint;
+    /** Parent grid reference */
+    grid: DataGrid;
+    /** Cell bounds */
+    bounds: CellBounds;
+    /** Row index */
+    rowIndex: number;
+    /** Column index */
+    colIndex: number;
+    /** Whether the cell is readonly */
+    readonly: boolean;
+    /** Whether the row is hovered */
+    isHoverRow: boolean;
+    /** Whether the cell is hovered */
+    isHoverCell: boolean;
+    /** Whether the cell is being edited */
+    isEditing: boolean;
+    /** Whether the row is checked/selected */
+    isChecked: boolean;
+    /** Cell background color */
+    fillColor: string;
+    /** Callback to request redraw */
+    requestRedraw: () => void;
+}
+/**
+ * Viewer interaction state for drag operations
+ */
+export interface ViewerDragState {
+    /** Whether the viewer is currently being dragged */
+    isDragging: boolean;
+    /** Starting X position of the drag */
+    startX: number;
+    /** Starting Y position of the drag */
+    startY: number;
+    /** Original value before drag started */
+    startValue: any;
+    /** Current cell bounds */
+    bounds: CellBounds;
+    /** Current viewer data */
+    data: CellViewerData;
+    /** Row index */
+    rowIndex: number;
+    /** Column index */
+    colIndex: number;
+}
+/**
+ * Base cell viewer interface
+ * All viewers must implement this interface
+ */
+export interface CellViewer<T extends CellViewerData = CellViewerData> {
+    /** Viewer type identifier */
+    readonly type: string;
+    /**
+     * Draw the cell content
+     * @param context Render context
+     * @param data Cell data
+     */
+    draw(context: ViewerRenderContext, data: T): void;
+    /**
+     * Optional: Handle click events on the cell
+     * @param context Render context
+     * @param data Cell data
+     * @param localX Click X position relative to cell
+     * @param localY Click Y position relative to cell
+     * @returns true if the event was handled
+     */
+    onClick?(context: ViewerRenderContext, data: T, localX: number, localY: number): boolean;
+    /**
+     * Optional: Handle double click events on the cell
+     * @param context Render context
+     * @param data Cell data
+     * @param localX Double click X position relative to cell
+     * @param localY Double click Y position relative to cell
+     * @returns true if the event was handled (prevents default edit behavior)
+     */
+    onDblClick?(context: ViewerRenderContext, data: T, localX: number, localY: number): boolean;
+    /**
+     * Optional: Get the preferred height for this cell
+     * @param context Render context
+     * @param data Cell data
+     * @returns Preferred height in pixels
+     */
+    getPreferredHeight?(context: ViewerRenderContext, data: T): number;
+    /**
+     * Optional: Check if mouse is over an interactive area (e.g., drag handle)
+     * @param context Render context
+     * @param data Cell data
+     * @param localX Mouse X position relative to cell
+     * @param localY Mouse Y position relative to cell
+     * @returns Cursor style if over interactive area, null otherwise
+     */
+    getInteractiveCursor?(context: ViewerRenderContext, data: T, localX: number, localY: number): string | null;
+    /**
+     * Optional: Handle mouse down for drag operations
+     * @param context Render context
+     * @param data Cell data
+     * @param localX Mouse X position relative to cell
+     * @param localY Mouse Y position relative to cell
+     * @returns true if drag operation started
+     */
+    onDragStart?(context: ViewerRenderContext, data: T, localX: number, localY: number): boolean;
+    /**
+     * Optional: Handle drag move
+     * @param context Render context
+     * @param data Cell data
+     * @param localX Current mouse X position relative to cell
+     * @param localY Current mouse Y position relative to cell
+     * @param startX Starting mouse X position
+     * @param startY Starting mouse Y position
+     * @returns New value if changed, undefined otherwise
+     */
+    onDragMove?(context: ViewerRenderContext, data: T, localX: number, localY: number, startX: number, startY: number): any;
+    /**
+     * Optional: Handle drag end
+     * @param context Render context
+     * @param data Cell data
+     * @param newValue The final value after dragging
+     */
+    onDragEnd?(context: ViewerRenderContext, data: T, newValue: any): void;
+}
+/**
+ * Base cell viewer data interface
+ * All specific data types extend this interface
+ */
+export interface CellViewerData {
+    /** Raw value stored in the cell */
+    value: any;
+    /** Display label (may differ from value) */
+    label?: string;
+    /** Options for select-type viewers */
+    options?: ViewerOption[];
+    /** Custom style overrides */
+    style?: ViewerStyle;
+    /** Extra data for specific viewers */
+    extra?: Record<string, any>;
+}
+/**
+ * Option item for select-type viewers
+ */
+export interface ViewerOption {
+    value: any;
+    label: string;
+    color?: string;
+    backgroundColor?: string;
+    icon?: string;
+}
+/**
+ * Style configuration for viewers
+ */
+export interface ViewerStyle {
+    color?: string;
+    backgroundColor?: string;
+    borderColor?: string;
+    fontSize?: number;
+    fontWeight?: 'normal' | 'bold';
+    textAlign?: 'left' | 'center' | 'right';
+    textBaseline?: 'top' | 'middle' | 'bottom';
+    padding?: number;
+}
+/**
+ * Text viewer data
+ */
+export interface TextViewerData extends CellViewerData {
+    value: string | number | null;
+    /** Text alignment */
+    textAlign?: 'left' | 'center' | 'right';
+    /** Background color for label mode */
+    backgroundColor?: string;
+    /** Whether to render as a tag/badge */
+    asTag?: boolean;
+    /** Tag border radius */
+    tagRadius?: number;
+    /** Rich text HTML content */
+    richText?: string;
+    /** Placeholder for empty values */
+    placeholder?: string;
+}
+/**
+ * Select viewer data (single/multi select)
+ */
+export interface SelectViewerData extends CellViewerData {
+    value: any | any[];
+    /** Available options */
+    options: ViewerOption[];
+    /** Whether multiple selection is allowed */
+    multiple?: boolean;
+    /** Show dropdown arrow */
+    showArrow?: boolean;
+    /** Max tags to display (for multiple mode) */
+    maxTags?: number;
+}
+/**
+ * Image viewer data
+ */
+export interface ImageViewerData extends CellViewerData {
+    value: string | null;
+    /** Alternative text */
+    alt?: string;
+    /** Placeholder image URL */
+    placeholder?: string;
+    /** Image fit mode */
+    fit?: 'contain' | 'cover' | 'fill';
+    /** Border radius */
+    borderRadius?: number;
+    /** Whether the image is animated (GIF) */
+    animated?: boolean;
+}
+/**
+ * Person/User viewer data
+ */
+export interface PersonViewerData extends CellViewerData {
+    value: PersonInfo | PersonInfo[] | null;
+    /** Display mode */
+    mode?: 'avatar' | 'name' | 'both';
+    /** Avatar size */
+    avatarSize?: number;
+    /** Max persons to display */
+    maxDisplay?: number;
+    /** Placeholder text for empty */
+    placeholder?: string;
+}
+/**
+ * Person information
+ */
+export interface PersonInfo {
+    id: string | number;
+    name: string;
+    avatar?: string;
+    email?: string;
+}
+/**
+ * Progress viewer data
+ */
+export interface ProgressViewerData extends CellViewerData {
+    value: number;
+    /** Minimum value (default 0) */
+    min?: number;
+    /** Maximum value (default 100) */
+    max?: number;
+    /** Progress bar height */
+    barHeight?: number;
+    /** Show percentage text */
+    showText?: boolean;
+    /** Text position */
+    textPosition?: 'inside' | 'outside' | 'right';
+    /** Progress color (or auto based on value) */
+    color?: string;
+    /** Track/background color */
+    trackColor?: string;
+    /** Color thresholds for automatic coloring */
+    colorThresholds?: Array<{
+        value: number;
+        color: string;
+    }>;
+    /** Whether the progress bar is draggable to change value */
+    draggable?: boolean;
+}
+/**
+ * Datetime viewer data
+ */
+export interface DatetimeViewerData extends CellViewerData {
+    value: string | number | Date | null;
+    /** Date format string */
+    format?: string;
+    /** Display type */
+    displayType?: 'date' | 'time' | 'datetime' | 'month';
+    /** Show icon */
+    showIcon?: boolean;
+    /** Placeholder for invalid/empty dates */
+    placeholder?: string;
+}
+/**
+ * Boolean/Checkbox viewer data
+ */
+export interface BooleanViewerData extends CellViewerData {
+    value: boolean | null;
+    /** Display style */
+    displayStyle?: 'checkbox' | 'switch' | 'text';
+    /** Text for true value */
+    trueText?: string;
+    /** Text for false value */
+    falseText?: string;
+    /** Text for null/indeterminate value */
+    nullText?: string;
+    /** Check icon color */
+    checkedColor?: string;
+    /** Uncheck icon color */
+    uncheckedColor?: string;
+}
+/**
+ * Status viewer data
+ */
+export interface StatusViewerData extends CellViewerData {
+    value: string | number;
+    /** Status configurations */
+    options: StatusOption[];
+    /** Show status icon */
+    showIcon?: boolean;
+    /** Show as tag/badge */
+    asTag?: boolean;
+}
+/**
+ * Status option configuration
+ */
+export interface StatusOption extends ViewerOption {
+    /** Status icon */
+    icon?: 'dot' | 'check' | 'cross' | 'warning' | 'info' | string;
+    /** Status type for automatic styling */
+    type?: 'success' | 'warning' | 'error' | 'info' | 'default';
+}
+/**
+ * Group header viewer data
+ */
+export interface GroupHeaderViewerData extends CellViewerData {
+    value: string;
+    /** Group display label */
+    label: string;
+    /** Number of records in group */
+    count?: number;
+    /** Whether the group is expanded */
+    expanded?: boolean;
+    /** Nesting level (for multi-level groups) */
+    level?: number;
+    /** Group type */
+    groupType?: 'text' | 'person' | 'status' | 'date';
+    /** Group icon */
+    icon?: string;
+    /** Person info for person-type groups */
+    person?: PersonInfo;
+    /** Whether to show count badge */
+    showCount?: boolean;
+    /** Whether to show working hours icon */
+    showUserWorkingHours?: boolean;
+}
+/**
+ * Separator row viewer data
+ */
+export interface SeparatorRowViewerData extends CellViewerData {
+    value: null | undefined;
+    /** Separator nesting level */
+    separateLevel?: number;
+    /** Group level context */
+    groupLevel?: number;
+    /** Whether this is the end level */
+    isEndLevel?: boolean;
+    /** Row height override */
+    rowHeight?: number;
+}
+/**
+ * Tree node item for tree dropdown
+ */
+export interface TreeNodeItem {
+    value: string | number;
+    label: string;
+    path?: string;
+    children?: TreeNodeItem[];
+}
+/**
+ * Tree dropdown viewer data
+ */
+export interface TreeDropdownViewerData extends CellViewerData {
+    value: string | string[] | TreeNodeItem[] | null;
+    /** Path separator character */
+    pathSeparator?: string;
+    /** Whether to show full path or only the last segment */
+    showFullPath?: boolean;
+    /** Max tags to display */
+    maxTags?: number;
+    /** Placeholder for empty values */
+    placeholder?: string;
+    /** Tag background color */
+    tagBackgroundColor?: string;
+    /** Tag border color */
+    tagBorderColor?: string;
+    /** Tag text color */
+    tagColor?: string;
+}
+/**
+ * Punch (打卡进度) viewer data
+ */
+export interface PunchViewerData extends CellViewerData {
+    value: PunchValue | null;
+    /** 数据行 ID */
+    id?: string | number;
+    /** 属性 key */
+    key?: string;
+    /** 是否可编辑 */
+    canEdit?: boolean;
+    /** 是否显示删除线 */
+    showLineThrow?: boolean;
+    /** 日期显示模式 */
+    datePattern?: string;
+    /** 是否关联属性 */
+    isLink?: boolean;
+    /** 关联 key */
+    linkKey?: string;
+    /** 是否有错误 */
+    error?: {
+        errorProperty?: string;
+        errorMessage?: string;
+    } | null;
+}
+/**
+ * 打卡值
+ */
+export interface PunchValue {
+    /** 打卡记录 ID，> 0 表示已打卡 */
+    punch_id?: number;
+    /** 打卡日期时间戳 */
+    created_date?: number;
+    /** 进度 0~1 */
+    progress?: number;
+    /** 审批状态 */
+    review_status?: number | string;
+    /** 是否已读 */
+    is_read?: boolean;
+}
+/**
+ * Module information
+ */
+export interface ModuleInfo {
+    /** Module unique identifier */
+    id: string;
+    /** Module display name */
+    name: string;
+    /** Module color for tag background (optional) */
+    color?: string;
+}
+/**
+ * Module viewer data
+ */
+export interface ModuleViewerData extends CellViewerData {
+    /** Module(s) - ModuleInfo object(s), string ID(s) as fallback, or null */
+    value: ModuleInfo | ModuleInfo[] | string | string[] | null;
+    /** Whether to show colored tags (default true) */
+    showColor?: boolean;
+    /** Maximum number of modules to display (default 3) */
+    maxDisplay?: number;
+    /** Placeholder text for empty values (default '-') */
+    placeholder?: string;
+}
+/**
+ * Text viewer with switcher data (tree expand/collapse + task name)
+ */
+export interface TextViewerWithSwitcherData extends CellViewerData {
+    value: string | number | null;
+    /** Display label (overrides value when present) */
+    label?: string;
+    /** Custom text color (default '#333') */
+    color?: string;
+    /** Whether the node is expanded */
+    expanded?: boolean;
+    /** Whether the node has children */
+    hasChildren?: boolean;
+    /** Whether the node is loading children */
+    loading?: boolean;
+    /** Tree indentation level (0 = root) */
+    tableTreeLevel?: number;
+    /** Array indicating whether each ancestor is the last leaf at its level */
+    isLastLeafArr?: boolean[];
+    /** Task icon file URL (dynamically loaded from data source) */
+    iconFile?: string;
+    /** Child node count */
+    count?: number;
+    /** Whether the node has downstream nodes */
+    hasDownstreamNode?: boolean;
+    /** Rich text HTML content */
+    richText?: string;
+    /** Placeholder for empty values */
+    placeholder?: string;
+    /** Whether this is a linked task */
+    isLinkTask?: boolean;
+    /** Linked task icon file URL */
+    linkIconFile?: string;
+    /** Whether to show strikethrough on text */
+    showLineThrough?: boolean;
+    /** Whether to show weakened (dimmed) text */
+    weakenWord?: boolean;
+    /** Text alignment */
+    textAlign?: 'left' | 'center' | 'right';
+    /** Error/warning state */
+    error?: {
+        errorProperty?: string;
+        errorMessage?: string;
+        is_warning?: boolean;
+        is_level_1_error?: boolean;
+    };
+}
+/**
+ * 文件项信息
+ */
+export interface FileItem {
+    /** 文件名 */
+    name: string;
+    /** 文件格式/后缀 */
+    fileFormat?: string;
+    /** 预览图片 URL */
+    previewUrl?: string;
+    /** 是否正在上传/处理中 */
+    doing?: boolean;
+    /** 文件资产 ID */
+    assetId?: number;
+    /** 文件状态 */
+    status?: number;
+}
+/**
+ * 文件 Viewer 数据接口
+ */
+export interface FileViewerData extends CellViewerData {
+    /** 文件列表 */
+    value: FileItem[] | null;
+    /** 数据行 ID */
+    id?: string | number;
+    /** 属性 key */
+    key?: string;
+    /** 是否可编辑 */
+    canEdit?: boolean;
+    /** 是否显示删除线 */
+    showLineThrow?: boolean;
+    /** 是否关联属性 */
+    isLink?: boolean;
+    /** 关联 key */
+    linkKey?: string;
+    /** 关联数据行 ID */
+    linkedId?: string | number;
+    /** 文件元数据 key */
+    fileMeta?: string;
+    /** 是否有错误 */
+    error?: {
+        errorProperty?: string;
+        errorMessage?: string;
+    } | null;
+    /** 是否仅显示缩略图（隐藏文件名） */
+    isDisplayThumbnail?: boolean;
+}
+/**
+ * HyperLink text viewer data (超链接文本)
+ */
+export interface HyperlinkTextViewerData extends CellViewerData {
+    /** 值格式：[显示文本, 链接URL] 或 null */
+    value: [string, string] | null;
+    /** 数据行 ID */
+    id?: string | number;
+    /** 属性 key */
+    key?: string;
+    /** 是否可编辑 */
+    canEdit?: boolean;
+    /** 是否显示删除线 */
+    showLineThrow?: boolean;
+    /** 是否关联属性 */
+    isLink?: boolean;
+    /** 关联 key */
+    linkKey?: string;
+    /** 是否有错误 */
+    error?: {
+        errorProperty?: string;
+        errorMessage?: string;
+    } | null;
+}
+/**
+ * 工作流状态 Viewer 数据接口
+ */
+export interface WfStateViewerData extends CellViewerData {
+    /** 工作流状态 ID，支持数字、包含 id 的对象、或 null */
+    value: number | {
+        id: number;
+    } | null;
+    /** 状态显示名称 */
+    displayName?: string;
+    /** 状态大类（如 'toStart' | 'inProgress' | 'complete' | 'rejected' | 'paused'） */
+    stateType?: string;
+    /** 图标颜色 */
+    iconColor?: string;
+    /** 文字颜色 */
+    color?: string;
+    /** 图标类型标识 */
+    icon?: string;
+    /** 额外信息，非空时显示角标 */
+    extraInfo?: Record<string, any> | null;
+    /** 空值时的占位文本 */
+    placeholder?: string;
+}
+/**
+ * Module info for an upstream field item
+ */
+export interface IUpstreamModule {
+    /** Module display name (e.g. '原画', '建模') */
+    displayName: string;
+    /** Module tag background color */
+    bgColor: string;
+}
+/**
+ * Reminder properties for an incomplete upstream field item
+ */
+export interface IUpstreamReminderProperties {
+    /** Reminder display text (e.g. '等待上游', '已超期') */
+    displayName: string;
+    /** Optional background color for the reminder tag */
+    bgColor?: string;
+    /** Whether this is a first-edition completion time */
+    isFirstEditionTime?: boolean;
+    [key: string]: any;
+}
+/**
+ * Sync property representing a single resource preview
+ */
+export interface IUpstreamSyncProperty {
+    /** Resource asset ID */
+    assetId: number;
+    /** Resource display name (e.g. 'asset_001.png') */
+    displayName: string;
+    /** File format extension (e.g. 'png', 'psd', 'fbx') */
+    fileFormat: string;
+    /** Preview image URL (empty string if no preview available) */
+    imageUrl: string;
+}
+/**
+ * A single upstream field view item representing one upstream dependency
+ */
+export interface IUpstreamFieldViewItem {
+    /** Unique node identifier */
+    nodeId: number;
+    /** Module info with display name and color */
+    module: IUpstreamModule;
+    /** Whether the upstream dependency is completed */
+    isAvailable: boolean;
+    /** Reminder properties (present when isAvailable is false) */
+    reminderProperties?: IUpstreamReminderProperties;
+    /** Sync resource previews (present when isAvailable is true) */
+    syncProperties?: IUpstreamSyncProperty[];
+}
+/**
+ * Upstream viewer data - displays upstream dependency status
+ */
+export interface UpstreamViewerData extends CellViewerData {
+    /** Array of upstream field view items */
+    value: IUpstreamFieldViewItem[];
+}
+/**
+ * 任务节点项信息
+ */
+export interface TaskNodeItem {
+    /** 任务节点 ID */
+    id: number;
+    /** 任务节点名称 */
+    name: string;
+    /** 任务图标文件名（可选，无时显示默认图标） */
+    iconFile?: string;
+}
+/**
+ * 任务节点 Viewer 数据接口
+ */
+export interface TaskNodeViewerData extends CellViewerData {
+    /** 任务节点数据，支持数组、逗号分隔字符串、单个数字 */
+    value: TaskNodeItem[] | string | number | null;
+    /** 数据行 ID */
+    id?: string | number;
+    /** 属性 key */
+    key?: string;
+    /** 是否可编辑 */
+    canEdit?: boolean;
+    /** 是否为关联属性 */
+    isLink?: boolean;
+    /** 关联属性 key */
+    linkKey?: string;
+    /** 是否显示删除线 */
+    showLineThrow?: boolean;
+    /** 错误信息 */
+    error?: {
+        errorProperty?: string;
+        errorMessage?: string;
+        is_warning?: boolean;
+    } | null;
+    /** 自定义任务节点信息映射 */
+    customTaskNodeInfo?: Record<number, {
+        name: string;
+        iconFile?: string;
+    }>;
+}
+/**
+ * ITFS path viewer data
+ */
+export interface ItfsPathViewerData extends CellViewerData {
+    value: string | Record<string, any> | null;
+    /** Path text color (default: #268bfb) */
+    pathColor?: string;
+    /** Icon color (default: #8e8e8e) */
+    iconColor?: string;
+    /** Whether to show netdisc icon (default: true) */
+    showIcon?: boolean;
+    /** Placeholder for empty values */
+    placeholder?: string;
+}
+/**
+ * Nested grid viewer data
+ */
+export interface NestedGridViewerData extends CellViewerData {
+    value: any[];
+    /** Nested grid columns */
+    columns: NestedColumnConfig[];
+    /** Whether to show expand all button */
+    showExpandAll?: boolean;
+    /** Default display rows when collapsed */
+    displayRows?: number;
+    /** Whether currently expanded */
+    expanded?: boolean;
+}
+/**
+ * Nested column configuration
+ */
+export interface NestedColumnConfig {
+    key: string;
+    title: string;
+    width?: number;
+    type?: string;
+    align?: 'left' | 'center' | 'right';
+    [key: string]: any;
+}
+/**
+ * Viewer class constructor type
+ */
+export type ViewerConstructor<T extends CellViewerData = CellViewerData> = new () => CellViewer<T>;
+/**
+ * Viewer factory function type
+ */
+export type ViewerFactory<T extends CellViewerData = CellViewerData> = () => CellViewer<T>;
+/**
+ * Viewer type mapping
+ */
+export interface ViewerTypeMap {
+    text: TextViewerData;
+    select: SelectViewerData;
+    image: ImageViewerData;
+    person: PersonViewerData;
+    progress: ProgressViewerData;
+    datetime: DatetimeViewerData;
+    date: DatetimeViewerData;
+    time: DatetimeViewerData;
+    month: DatetimeViewerData;
+    boolean: BooleanViewerData;
+    checkbox: BooleanViewerData;
+    status: StatusViewerData;
+    'group-header': GroupHeaderViewerData;
+    'separator-row': SeparatorRowViewerData;
+    nested: NestedGridViewerData;
+    'tree-dropdown': TreeDropdownViewerData;
+    punch: PunchViewerData;
+    'punch-timing': PunchTimingViewerData;
+    hyperlink: HyperlinkTextViewerData;
+    file: FileViewerData;
+    'task-node': TaskNodeViewerData;
+    'wf-state': WfStateViewerData;
+    workflow: WorkflowViewerData;
+    'file-storage-spec': FileStorageSpecViewerData;
+    pivot: PivotViewerData;
+    module: ModuleViewerData;
+    'text-with-switcher': TextViewerWithSwitcherData;
+    upstream: UpstreamViewerData;
+    'table-action-button': TableActionButtonViewerData;
+    'priority-text': PriorityTextViewerData;
+    'status-text': StatusTextViewerData;
+    theme: ThemeViewerData;
+    'itfs-path': ItfsPathViewerData;
+    'deliverable-review': DeliverableReviewViewerData;
+    'rich-text': RichTextViewerData;
+}
+/**
+ * All supported viewer types
+ */
+export type ViewerType = keyof ViewerTypeMap;
+/**
+ * Cell data with viewer type
+ */
+export interface TypedCellData<T extends ViewerType = ViewerType> {
+    viewerType: T;
+    data: ViewerTypeMap[T];
+}
+/**
+ * Type guard for viewer data
+ */
+export declare function isTextViewerData(data: CellViewerData): data is TextViewerData;
+export declare function isSelectViewerData(data: CellViewerData): data is SelectViewerData;
+export declare function isPersonViewerData(data: CellViewerData): data is PersonViewerData;
+export declare function isProgressViewerData(data: CellViewerData): data is ProgressViewerData;
+export declare function isNestedGridViewerData(data: CellViewerData): data is NestedGridViewerData;
+/**
+ * 交付地址 Viewer 数据接口
+ * 接收业务层已处理好的地址字符串（URL 格式转换和权限脱敏由业务层完成）
+ */
+export interface FileStorageSpecViewerData extends CellViewerData {
+    /** 交付地址显示文本（业务层将原始 URL 经过格式转换和权限脱敏后传入） */
+    value: string | null;
+    /** 空值时的占位文本（默认 '-'） */
+    placeholder?: string;
+}
+/**
+ * 引用类型 Viewer 数据接口
+ * 接收业务层将引用属性值格式化后传入的显示文本
+ */
+export interface PivotViewerData extends CellViewerData {
+    /** 引用属性的格式化显示文本（由业务层将 pivotField 解析后传入） */
+    value: string | null;
+    /** 空值时的占位文本（默认 '-'） */
+    placeholder?: string;
+    /** 是否为关联属性（为 true 时显示关联图标） */
+    isLink?: boolean;
+}
+/**
+ * 工作流 Viewer 数据接口
+ * 接收业务层已转换好的工作流显示名称数组
+ */
+export interface WorkflowViewerData extends CellViewerData {
+    /** 工作流显示名称数组（由业务层将工作流 ID 通过 wfStateManager 转换后传入） */
+    value: string[];
+    /** 空值时的占位文本（默认 '-'） */
+    placeholder?: string;
+}
+/**
+ * Single button option for table action button viewer
+ */
+export interface TableActionButtonOption {
+    /** Button unique identifier */
+    name: string;
+    /** Button display text */
+    displayName: string;
+    /** Whether this is a super admin button (orange style) */
+    isSuperBtn?: boolean;
+    /** Whether this is an operation button (blue style) */
+    isOperationBtn?: boolean;
+    /** Custom background color */
+    backgroundColor?: string;
+    /** Custom text color */
+    color?: string;
+}
+/**
+ * Table action button viewer data
+ */
+export interface TableActionButtonViewerData extends CellViewerData {
+    /** Array of button options */
+    value: TableActionButtonOption[] | null;
+    /** Data row ID */
+    id?: string | number;
+    /** Property key */
+    key?: string;
+    /** Whether the buttons are editable/clickable */
+    canEdit?: boolean;
+    /** Whether this is a linked task (shows link icon, no buttons) */
+    isLinkTask?: boolean;
+    /** Whether to show link icon */
+    isLink?: boolean;
+    /** Link key */
+    linkKey?: string;
+    /** Button click callback */
+    onButtonClick?: (event: MouseEvent, payload: {
+        id: string | number;
+        operation: TableActionButtonOption;
+    }) => void;
+    /** Operation button click callback */
+    onOperationBtnClick?: (event: MouseEvent, payload: {
+        id: string | number;
+        data: TableActionButtonViewerData;
+    }) => void;
+    /** "More" button click callback */
+    onAfterClick?: (event: MouseEvent, payload: {
+        data: TableActionButtonViewerData;
+        position: {
+            x: number;
+            y: number;
+        };
+    }) => void;
+}
+/**
+ * 打卡时间查看器数据接口
+ * 用于显示打卡的时间信息，如00:00:00格式的时间显示
+ */
+export interface PunchTimingViewerData extends CellViewerData {
+    /** 时间值，支持字符串格式如'00:00:00'或时间戳 */
+    value: string | number | null;
+    /** 数据行 ID */
+    id?: string | number;
+    /** 属性 key */
+    key?: string;
+    /** 是否可编辑 */
+    canEdit?: boolean;
+    /** 是否显示删除线 */
+    showLineThrow?: boolean;
+    /** 是否关联属性 */
+    isLink?: boolean;
+    /** 关联 key */
+    linkKey?: string;
+    /** 是否有错误 */
+    error?: {
+        errorProperty?: string;
+        errorMessage?: string;
+    } | null;
+    /** 时间格式，默认'HH:mm:ss' */
+    timeFormat?: string;
+    /** 是否显示为24小时制 */
+    is24Hour?: boolean;
+    /** 是否显示毫秒 */
+    showMilliseconds?: boolean;
+    /** 占位符文本，默认'-' */
+    placeholder?: string;
+    /** 文本对齐方式 */
+    textAlign?: 'left' | 'center' | 'right';
+    /** 字体大小 */
+    fontSize?: number;
+    /** 字体颜色 */
+    color?: string;
+    /** 背景颜色 */
+    backgroundColor?: string;
+    /** 计时器状态 */
+    timerState?: {
+        /** 计时器ID */
+        timerId: number | null;
+        /** 开始时间戳 */
+        startTime: number | null;
+        /** 当前显示时间 */
+        currentTime: string;
+        /** 计时器状态 */
+        status: 'start' | 'pause';
+        /** 是否正在计时 */
+        isTiming: boolean;
+    };
+}
+/**
+ * 优先级文本 viewer 数据
+ * 用于展示优先级标签（P0-P4+），带有对应的颜色和背景色
+ */
+export interface PriorityTextViewerData extends CellViewerData {
+    /** 优先级值，支持数字或字符串（如 0, 1, 2, '0', '1'） */
+    value: string | number | null;
+    /** 文本对齐方式，默认 'center' */
+    textAlign?: 'left' | 'center' | 'right';
+    /** 标签圆角半径，默认 2 */
+    tagRadius?: number;
+    /** 占位符文本，默认 '-' */
+    placeholder?: string;
+}
+/**
+ * 状态枚举项
+ */
+export interface StatusTextEnum {
+    /** 状态值标识（如 'toStart', 'inProgress', 'complete'） */
+    value: string;
+    /** 状态显示名称（如 '未开始', '进行中', '已完成'） */
+    name: string;
+    /** 文字颜色 */
+    color: string;
+    /** 图标类型（'circle' | 'pause' | 'progress' | 'check' 或自定义字符串） */
+    icon: string;
+    /** 图标颜色 */
+    iconColor: string;
+}
+/**
+ * 状态文本 viewer 数据
+ * 用于展示状态标签（图标 + 状态名称），如 [●] 进行中
+ */
+export interface StatusTextViewerData extends CellViewerData {
+    /** 状态名称（匹配 statusList 中的 name 字段） */
+    value: string | null;
+    /** 自定义状态枚举列表，不传则使用默认状态列表 */
+    statusList?: StatusTextEnum[];
+    /** 是否显示图标，默认 true */
+    showIcon?: boolean;
+    /** 图标大小，默认 14 */
+    iconSize?: number;
+    /** 是否显示角标指示器，默认 false */
+    showCorner?: boolean;
+    /** 额外信息（当存在时且 showCorner 为 true 显示角标） */
+    extraInfo?: Record<string, any>;
+    /** 占位符文本，默认 '-' */
+    placeholder?: string;
+}
+/**
+ * 主题项信息
+ */
+export interface ThemeItem {
+    /** 主题唯一标识 */
+    id: string;
+    /** 主题显示标题 */
+    title: string;
+}
+/**
+ * 主题文本 viewer 数据
+ * 用于展示主题标签（图标 + 主题名称 + 后缀），如 [🎨] 主题A 等2个
+ */
+export interface ThemeViewerData extends CellViewerData {
+    /** 主题列表，支持 ThemeItem[] 或 string[] */
+    value: ThemeItem[] | string[] | null;
+    /** 是否显示图标，默认 true */
+    showIcon?: boolean;
+    /** 图标大小，默认 14 */
+    iconSize?: number;
+    /** 图标颜色，默认 '#8c8c8c' */
+    iconColor?: string;
+    /** 后缀文字颜色，默认 '#999' */
+    suffixColor?: string;
+    /** 占位符文本，默认 '-' */
+    placeholder?: string;
+}
+/**
+ * 交付物审核文件项
+ */
+export interface DeliverableReviewItem {
+    /** 文件名 */
+    name: string;
+    /** 文件格式/后缀 */
+    file_format?: string;
+    /** 预览图片 URL */
+    preview_url?: string;
+    /** 资产 ID */
+    asset_id?: number;
+    /** 审核 ID（> 0 表示为审核类型文件） */
+    review_id?: number;
+    /** 是否为审核类型 */
+    isReview?: boolean;
+}
+/**
+ * 交付物审核 viewer 数据
+ * 用于展示交付物审核文件列表（审核图标 + 文件名）
+ */
+export interface DeliverableReviewViewerData extends CellViewerData {
+    /** 审核文件列表 */
+    value: DeliverableReviewItem[] | null;
+    /** 数据行 ID */
+    id?: string | number;
+    /** 属性 key */
+    key?: string;
+    /** 是否可编辑 */
+    canEdit?: boolean;
+    /** 是否显示删除线 */
+    showLineThrow?: boolean;
+    /** 是否关联属性 */
+    isLink?: boolean;
+    /** 关联 key */
+    linkKey?: string;
+    /** 文件元数据 key */
+    fileMeta?: string;
+    /** 是否有错误 */
+    error?: {
+        errorProperty?: string;
+        errorMessage?: string;
+    } | null;
+    /** 占位符文本，默认 '-' */
+    placeholder?: string;
+}
+/**
+ * 富文本 viewer 数据
+ * 用于展示富文本内容，去除 HTML 标签后渲染纯文本
+ * <img> 标签显示为 [图片]，<video> 标签显示为 [视频]
+ */
+export interface RichTextViewerData extends CellViewerData {
+    /** HTML 富文本内容或纯文本 */
+    value: string | null;
+    /** 数据行 ID */
+    id?: string | number;
+    /** 属性 key */
+    key?: string;
+    /** 是否可编辑 */
+    canEdit?: boolean;
+    /** 是否显示删除线 */
+    showLineThrow?: boolean;
+    /** 是否关联属性 */
+    isLink?: boolean;
+    /** 关联 key */
+    linkKey?: string;
+    /** 是否有错误 */
+    error?: {
+        errorProperty?: string;
+        errorMessage?: string;
+    } | null;
+    /** 占位符文本，默认 '-' */
+    placeholder?: string;
+}