@fses/workbench-app 0.2.0 → 0.2.2

package/node_modules/@fses/workbench-card/src/renderers/native/nativeBindings.ts

@@ -0,0 +1,1096 @@
+/**
+ * @fileoverview 原生卡片绑定 - 提供表单、问卷、指标、列表、天气和普通图表 helper。
+ * @author seadon
+ * @created 2026-05-20
+ */
+import type { Component } from 'vue';
+import type {
+  ActionGroupData,
+  BlockVisualOptions,
+  CategoryRankingData,
+  CustomCanvasData,
+  DisplayBlockData,
+  FormBlockData,
+  FormField,
+  MetricSummaryData,
+  ReportBlockData,
+  SurveyBlockData,
+  TableRowsData,
+  TaskSummaryData,
+  WeatherCurrentData,
+  WorkbenchBlock,
+  WorkflowBlockData,
+} from '../../types';
+import type { WorkbenchBlockRendererProps } from '../useWorkbenchBlockRendererBindings';
+import {
+  imageTableColumnVisible,
+  structuredTableCellText,
+  visibleImageTableColumns,
+} from '../tableDisplay';
+
+type NativeBindingsContext = {
+  props: WorkbenchBlockRendererProps;
+  formValuesByBlock: Record<string, Record<string, unknown>>;
+  surveyAnswersByBlock: Record<string, Record<string, unknown>>;
+  formatMetricValue: (value: number, format?: string) => string;
+  isRecord: (value: unknown) => value is Record<string, unknown>;
+  dataBindingNeedsHumanIntervention: () => (block: WorkbenchBlock) => boolean;
+  imageComposeAlertRankingCard: () => (block: WorkbenchBlock, data: CategoryRankingData) => boolean;
+  imageComposeCompactCard: () => (block: WorkbenchBlock) => boolean;
+  imageComposeBusinessGapBadgeLabel: () => (block: WorkbenchBlock) => string;
+  referenceCompositeLooksLikeChairmanRiskDirectContext: () => (block: WorkbenchBlock, data: CustomCanvasData) => boolean;
+  CircleCheck: Component;
+  UserRound: Component;
+  LayoutDashboard: Component;
+  Bot: Component;
+  CloudRain: Component;
+  CloudSun: Component;
+};
+
+type ImageComposeMetricLeadingVisualKind = 'icon' | 'bars' | 'sparkline';
+type ImageComposeChartPreviewKind = 'line' | 'bar' | 'mixed' | 'donut';
+type ImageComposeChartPreviewBar = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  fill: string;
+  opacity: number;
+  label: string;
+};
+
+const IMAGE_COMPOSE_CHART_PREVIEW_MIN_BAR_COUNT = 4;
+
+export interface ImageComposeChartPreviewHeader {
+  label: string;
+  metric: string;
+  status: string;
+}
+
+/**
+ * Reads a table row as a loose record for image-composed fallback data.
+ * @param row - Candidate row payload.
+ * @returns Row record, or an empty record.
+ */
+function tableRowRecord(row: unknown): Record<string, unknown> {
+  return row && typeof row === 'object' && !Array.isArray(row)
+    ? row as Record<string, unknown>
+    : {};
+}
+
+/**
+ * Converts an unknown table value into display text.
+ * @param value - Candidate cell value.
+ * @returns Stable visible text for a table cell.
+ */
+function tableCellText(value: unknown): string {
+  return structuredTableCellText(value);
+}
+
+/**
+ * Resolves display columns for normal rows and object-row image fallbacks.
+ * @param columns - Optional declared table columns.
+ * @param rows - Table rows that may omit cells and columns.
+ * @returns Columns safe for rendering.
+ */
+export function tableColumnsFromRows(columns: unknown, rows: unknown): string[] {
+  const declaredColumns = visibleImageTableColumns(columns);
+  if (declaredColumns.length > 0) return declaredColumns;
+  const objectRows = Array.isArray(rows)
+    ? rows.map(tableRowRecord).filter((row) => Object.keys(row).some(imageTableColumnVisible))
+    : [];
+  const firstObjectRow = objectRows[0];
+  if (!firstObjectRow) return [];
+  const firstColumns = Object.keys(firstObjectRow).filter(imageTableColumnVisible);
+  const usesStableColumns = objectRows.every((row) => {
+    const rowColumns = Object.keys(row).filter(imageTableColumnVisible);
+    return rowColumns.length === firstColumns.length
+      && rowColumns.every((column, index) => column === firstColumns[index]);
+  });
+  // 异构对象行无法共享真实列头，统一降级为逐行键值摘要，避免后续行错列或整行空白。
+  return usesStableColumns ? firstColumns.slice(0, 3) : ['字段', '内容'];
+}
+
+/**
+ * Resolves visible cells from a declared row.cells array or key-value object row fallback.
+ * @param row - Table row payload.
+ * @param columns - Visible table columns.
+ * @returns Cell texts safe for Vue template iteration.
+ */
+export function tableRowCells(row: unknown, columns: string[]): string[] {
+  const record = tableRowRecord(row);
+  const cells = record.cells;
+  if (Array.isArray(cells)) {
+    return cells.slice(0, columns.length).map(tableCellText);
+  }
+  const usesKeyValueFallback = columns.length === 2
+    && columns[0] === '字段'
+    && columns[1] === '内容'
+    && !columns.every((column) => Object.prototype.hasOwnProperty.call(record, column));
+  const entries = Object.entries(record)
+    .filter(([key]) => imageTableColumnVisible(key))
+    .map(([key, value]) => {
+      const text = tableCellText(value);
+      return usesKeyValueFallback && text ? `${key}：${text}` : text;
+    })
+    .filter(Boolean);
+  return entries.slice(0, columns.length);
+}
+
+/**
+ * Creates native card helpers used by WorkbenchBlockRenderer.
+ * @param context - Shared renderer state and utilities.
+ * @returns Native renderer helper functions.
+ */
+export function createNativeBindings(context: NativeBindingsContext) {
+  const {
+    props,
+    formValuesByBlock,
+    surveyAnswersByBlock,
+    formatMetricValue,
+    isRecord,
+    dataBindingNeedsHumanIntervention,
+    imageComposeAlertRankingCard,
+    imageComposeCompactCard,
+    imageComposeBusinessGapBadgeLabel,
+    referenceCompositeLooksLikeChairmanRiskDirectContext,
+    CircleCheck,
+    UserRound,
+    LayoutDashboard,
+    Bot,
+    CloudRain,
+    CloudSun,
+  } = context;
+
+  function isFormBlockData(value: unknown): value is FormBlockData {
+    return Boolean(value && typeof value === 'object' && Array.isArray((value as FormBlockData).fields));
+  }
+  
+  function isSurveyBlockData(value: unknown): value is SurveyBlockData {
+    return Boolean(value && typeof value === 'object' && Array.isArray((value as SurveyBlockData).questions));
+  }
+  
+  function isActionGroupData(value: unknown): value is ActionGroupData {
+    return Boolean(value && typeof value === 'object' && Array.isArray((value as ActionGroupData).buttons));
+  }
+  
+  function isWorkflowBlockData(value: unknown): value is WorkflowBlockData {
+    return Boolean(value && typeof value === 'object' && Array.isArray((value as WorkflowBlockData).steps));
+  }
+  
+  function isReportBlockData(value: unknown): value is ReportBlockData {
+    return Boolean(value && typeof value === 'object' && Array.isArray((value as ReportBlockData).sections));
+  }
+  
+  function textValue(value: unknown, fallback = '') {
+    return typeof value === 'string' && value.trim() ? value.trim() : fallback;
+  }
+  
+  function numberValue(value: unknown, fallback = 0) {
+    const numeric = Number(value);
+    return Number.isFinite(numeric) ? numeric : fallback;
+  }
+  
+  function listValue(value: unknown): Record<string, unknown>[] {
+    return Array.isArray(value) ? value.filter(isRecord) : [];
+  }
+  
+  function metaRecord(block: WorkbenchBlock, key: string) {
+    const value = block.meta?.[key];
+    return isRecord(value) ? value : {};
+  }
+  
+  function metaList(block: WorkbenchBlock, key: string) {
+    return listValue(block.meta?.[key]);
+  }
+
+  /**
+   * Reads the original image-grid width for a reconstructed image card.
+   * @param block - Rendered workbench block.
+   * @returns Image layout width when present.
+   */
+  function imageComposeLayoutBasisWidth(block: WorkbenchBlock): number {
+    const basis = metaRecord(block, 'layoutBasis');
+    return numberValue(basis.w, numberValue(block.layout?.w, 0));
+  }
+  
+  function welcomeBannerMetrics(block: WorkbenchBlock) {
+    return metaList(block, 'portalMetrics').map((metric) => ({
+      label: textValue(metric.label),
+      value: textValue(metric.value, String(metric.value ?? '--')),
+      hint: textValue(metric.hint),
+    }));
+  }
+  
+  function tierKeyForDensity(density: 'thumbnail' | 'compact' | 'standard' | 'expanded') {
+    if (density === 'thumbnail' || density === 'compact') return 'compact';
+    return density;
+  }
+  
+  function applyResponsiveTier(block: WorkbenchBlock, density: 'thumbnail' | 'compact' | 'standard' | 'expanded'): WorkbenchBlock {
+    const tiers = block.meta?.responsiveContentTiers;
+    if (!tiers) return block;
+    const preferred = tiers[tierKeyForDensity(density)] || (density === 'expanded' ? tiers.standard || tiers.compact : density === 'standard' ? tiers.compact : undefined);
+    if (!preferred) return block;
+    return {
+      ...block,
+      title: preferred.title || block.title,
+      subtitle: preferred.subtitle ?? block.subtitle,
+      subType: preferred.subType || block.subType,
+      renderer: preferred.renderer || block.renderer,
+      data: preferred.data || block.data,
+      meta: { ...block.meta, visual: { ...(block.meta?.visual || {}), ...(preferred.visual || {}) } },
+    };
+  }
+  
+  function formValues(blockId: string) {
+    if (!formValuesByBlock[blockId]) formValuesByBlock[blockId] = {};
+    return formValuesByBlock[blockId];
+  }
+  
+  function surveyAnswers(blockId: string) {
+    if (!surveyAnswersByBlock[blockId]) surveyAnswersByBlock[blockId] = {};
+    return surveyAnswersByBlock[blockId];
+  }
+  
+  /**
+   * Applies density-aware list limits while tolerating optional list fields.
+   * @param items - Source list, or an empty value when the data shape omits optional details.
+   * @param thumbnail - Maximum items in thumbnail density.
+   * @param compact - Maximum items in compact density.
+   * @returns List trimmed for the current density.
+   */
+  function compactLimit<T>(items: T[] | undefined | null, thumbnail: number, compact: number) {
+    // 部分业务数据只提供核心指标字段，缺省的明细列表按空列表渲染，避免整张卡片渲染中断。
+    const safeItems = Array.isArray(items) ? items : [];
+    if (props.density === 'thumbnail') return safeItems.slice(0, thumbnail);
+    if (props.density === 'compact') return safeItems.slice(0, compact);
+    return safeItems;
+  }
+  
+  function toggleMultiValue(currentValue: unknown, option: string) {
+    const values = Array.isArray(currentValue) ? currentValue.map(String) : [];
+    return values.includes(option) ? values.filter((item) => item !== option) : [...values, option];
+  }
+  
+  function formCompletedCount(blockId: string, data: FormBlockData) {
+    const values = formValues(blockId);
+    return data.fields.filter((field) => {
+      const value = values[field.id];
+      return typeof value === 'string' ? value.trim().length > 0 : Boolean(value);
+    }).length;
+  }
+  
+  function renderFieldType(field: FormField) {
+    if (field.type === 'number' || field.type === 'currency') return 'number';
+    if (field.type === 'date') return 'date';
+    return 'text';
+  }
+  
+  function updateMatrixAnswer(blockId: string, questionId: string, row: string, option: string) {
+    const answers = surveyAnswers(blockId);
+    const current = isRecord(answers[questionId]) ? answers[questionId] : {};
+    answers[questionId] = { ...current, [row]: option };
+  }
+  
+  function matrixAnswerValue(blockId: string, questionId: string, row: string) {
+    const value = surveyAnswers(blockId)[questionId];
+    return isRecord(value) ? value[row] : undefined;
+  }
+  
+  function multipleAnswerIncludes(blockId: string, questionId: string, option: string) {
+    const value = surveyAnswers(blockId)[questionId];
+    return Array.isArray(value) && value.map(String).includes(option);
+  }
+  
+  function taskStatusClass(status: TaskSummaryData['items'][number]['status']) {
+    return {
+      pending: 'bg-amber-50 text-amber-700',
+      reading: 'bg-[#edf3ff] text-[#1f4fd4]',
+      submitted: 'bg-emerald-50 text-emerald-700',
+      overdue: 'bg-rose-50 text-rose-700',
+      done: 'bg-slate-100 text-slate-600',
+    }[status] || 'bg-slate-100 text-slate-600';
+  }
+  
+  function taskTypeLabel(type: TaskSummaryData['items'][number]['type']) {
+    return { form: '表单', survey: '问卷', notice: '公告', document: '公文', workflow: '流程', custom: '定制' }[type] || type;
+  }
+  
+  function taskStatusLabel(status: TaskSummaryData['items'][number]['status']) {
+    return { pending: '待处理', reading: '待阅读', submitted: '已提交', overdue: '逾期', done: '完成' }[status] || status;
+  }
+
+  const TABLE_ROWS_PREVIEW_VISUAL_KINDS = new Set([
+    'tableRecordList',
+    'tableCompactList',
+    'tableSummary',
+    'tableComparison',
+    'tableParameter',
+    'tableIndex',
+    'tablePartition',
+    'tableMapping',
+    'tableLevel',
+    'tableDescription',
+    'tableTimeline',
+    'tableSteps',
+    'tableMatrix',
+    'tableNested',
+    'identityDirectory',
+    'workflowApprovalList',
+  ]);
+
+  /**
+   * Reads the supported rows preview visual kind.
+   * @param data - Candidate rows data.
+   * @param block - Rendered block, when available.
+   * @returns Supported preview visual kind, or an empty string.
+   */
+  function tableRowsPreviewVisualKind(data: DisplayBlockData | undefined, block?: WorkbenchBlock): string {
+    if (!data || data.shape !== 'rows' || !isRecord(data)) return '';
+    const visualKind = textValue(data.visualKind);
+    if (TABLE_ROWS_PREVIEW_VISUAL_KINDS.has(visualKind)) return visualKind;
+    return tableRowsPreviewVisualKindFromCapability(data, block);
+  }
+
+  /**
+   * Checks whether rows data may use the system-card preview renderer.
+   * @param block - Rendered block.
+   * @param data - Candidate rows data.
+   * @returns True when the rows came from system preview/default canvas samples.
+   */
+  function tableRowsPreviewCard(block: WorkbenchBlock, data: DisplayBlockData | undefined): boolean {
+    if (!tableRowsPreviewVisualKind(data, block)) return false;
+    const record: Record<string, unknown> = isRecord(data) ? data : {};
+    const sourceType = textValue(block.source?.sourceType);
+    const sourceLabel = textValue(record.sourceLabel);
+    return Boolean(block.meta?.systemCardPreview)
+      || (sourceType === 'canvas_runtime' && sourceLabel === 'Canvas Runtime')
+      || tableRowsPreviewCapabilityId(block, data).startsWith('card.table.');
+  }
+
+  /**
+   * Infers rows preview kind from an explicit registered table capability.
+   * @param data - Candidate rows data.
+   * @param block - Rendered block, when available.
+   * @returns Preview kind matching the table capability, or an empty string.
+   */
+  function tableRowsPreviewVisualKindFromCapability(data: DisplayBlockData | undefined, block?: WorkbenchBlock): string {
+    const capabilityId = tableRowsPreviewCapabilityId(block, data);
+    if (!capabilityId.startsWith('card.table.')) return '';
+    const tableKind = capabilityId.slice('card.table.'.length);
+    const visualKind = `table${tableKind.slice(0, 1).toUpperCase()}${tableKind.slice(1)}`;
+    return TABLE_ROWS_PREVIEW_VISUAL_KINDS.has(visualKind) ? visualKind : '';
+  }
+
+  /**
+   * Reads the registered table capability from block metadata or rows data.
+   * @param block - Rendered block, when available.
+   * @param data - Candidate rows data.
+   * @returns Capability id, or an empty string.
+   */
+  function tableRowsPreviewCapabilityId(block?: WorkbenchBlock, data?: DisplayBlockData): string {
+    const record: Record<string, unknown> = isRecord(data) ? data : {};
+    return textValue(block?.meta?.capabilityId)
+      || textValue(record.capabilityId);
+  }
+
+  /**
+   * Converts rows data into column-addressable records for preview layouts.
+   * @param data - Candidate rows data.
+   * @returns Row records keyed by visible column.
+   */
+  function tableRowsPreviewRecords(data: DisplayBlockData | undefined): Array<Record<string, string>> {
+    if (!data || data.shape !== 'rows') return [];
+    const rowsData = data as TableRowsData;
+    const columns = visibleImageTableColumns(rowsData.columns);
+    const rows = Array.isArray(rowsData.rows) ? rowsData.rows : [];
+    return rows.map((row, rowIndex) => {
+      const record: Record<string, string> = { id: textValue(row.id, `row-${rowIndex + 1}`) };
+      const rowRecord = tableRowRecord(row);
+      const cells = Array.isArray(rowRecord.cells) ? rowRecord.cells : [];
+      columns.forEach((column, columnIndex) => {
+        record[column] = structuredTableCellText(rowRecord[column] ?? cells[columnIndex]);
+      });
+      return record;
+    });
+  }
+
+  /**
+   * Reads one preview cell by column name.
+   * @param row - Row record.
+   * @param column - Column name.
+   * @returns Cell text.
+   */
+  function tableRowsPreviewCell(row: Record<string, string>, column: string): string {
+    return row[column] || '';
+  }
+
+  /**
+   * Reads the primary text for timeline/steps rows while supporting two-column query results.
+   * @param row - Preview row record.
+   * @param columns - Visible columns.
+   * @returns Main timeline label.
+   */
+  function tableRowsTimelinePrimaryCell(row: Record<string, string>, columns: string[]): string {
+    return tableRowsPreviewCell(row, columns.length > 2 ? columns[1] : columns[0]);
+  }
+
+  /**
+   * Reads the trailing badge text for timeline/steps rows while supporting two-column query results.
+   * @param row - Preview row record.
+   * @param columns - Visible columns.
+   * @returns Timeline badge text.
+   */
+  function tableRowsTimelineBadgeCell(row: Record<string, string>, columns: string[]): string {
+    return tableRowsPreviewCell(row, columns.length > 2 ? columns[2] : columns[1]);
+  }
+
+  /**
+   * Builds stable grid columns for rows preview cards.
+   * @param columns - Visible columns.
+   * @returns Inline grid style.
+   */
+  function tableRowsPreviewGridStyle(columns: string[]): Record<string, string> {
+    const count = Math.max(1, columns.length);
+    if (count === 3) return { gridTemplateColumns: '0.72fr minmax(0,1.1fr) 0.72fr' };
+    if (count === 4) return { gridTemplateColumns: '0.86fr repeat(3, minmax(0,1fr))' };
+    return { gridTemplateColumns: `repeat(${count}, minmax(0, 1fr))` };
+  }
+  
+  function formatWeatherTemp(value: number | null | undefined) {
+    return typeof value === 'number' ? `${value}°C` : '--';
+  }
+  
+  function weatherIcon(condition: WeatherCurrentData['condition']) {
+    return condition === 'rain' || condition === 'storm' || condition === 'snow' ? CloudRain : CloudSun;
+  }
+  
+  function isChartShape(data?: DisplayBlockData) {
+    return Boolean(data && [
+      'singleSeries',
+      'multiSeries',
+      'waterfallSteps',
+      'heatmapMatrix',
+      'pieSlices',
+      'radarMetrics',
+      'scatterPoints',
+      'funnelStages',
+      'gaugeMetric',
+      'mapRegions',
+      'sankeyFlow',
+      'treeHierarchy',
+      'ganttTasks',
+      'candlestickSeries',
+      'boxplotSeries',
+      'paretoSeries',
+      'networkGraph',
+      'echartsOption',
+      'echartsScript',
+      'protocolRender',
+    ].includes(data.shape));
+  }
+  
+  /**
+   * Checks whether an image-composed chart has no trustworthy data but still needs a screenshot-like preview.
+   * @param block - Rendered chart block.
+   * @param data - Current chart renderer data.
+   * @returns True when the body would otherwise be blank while the binding asks for business input.
+   */
+  function imageComposeEmptyChartPreview(block: WorkbenchBlock, data?: DisplayBlockData): boolean {
+    if (!imageComposeCompactCard()(block) || !dataBindingNeedsHumanIntervention()(block) || !isRecord(data)) return false;
+    const shape = textValue(data.shape);
+    const series = data.series;
+    if (shape === 'singleSeries' || shape === 'multiSeries') return !Array.isArray(series) || series.length === 0;
+    return false;
+  }
+
+  /**
+   * Checks whether an image-composed chart should keep its screenshot-like visual shell.
+   * @param block - Rendered chart block.
+   * @param data - Current chart renderer data.
+   * @returns True when a chart originated from image reconstruction.
+   */
+  function imageComposeChartPreview(block: WorkbenchBlock, data?: DisplayBlockData): boolean {
+    if (!imageComposeCompactCard()(block) || !isChartShape(data)) return false;
+    if (data?.shape === 'echartsOption' || data?.shape === 'echartsScript' || data?.shape === 'protocolRender') return false;
+    return true;
+  }
+
+  /**
+   * Chooses the small KPI visual from generic image layout and visual metadata.
+   * @param block - Rendered metric block.
+   * @returns Generic leading visual kind for the compact metric renderer.
+   */
+  function imageComposeMetricLeadingVisualKind(block: WorkbenchBlock): ImageComposeMetricLeadingVisualKind {
+    const visual = visualFor(block) as BlockVisualOptions & Record<string, unknown>;
+    const visualKind = textValue(
+      visual.visualKind,
+      textValue(block.meta?.visualKind, textValue(block.meta?.previewKind)),
+    );
+    const basisWidth = imageComposeLayoutBasisWidth(block);
+    if (/spark|line|trend/i.test(visualKind)) return 'sparkline';
+    if (/bar|column|chart/i.test(visualKind)) return 'bars';
+    if (/icon|avatar|logo|badge/i.test(visualKind)) return 'icon';
+    if (basisWidth > 0 && basisWidth <= 12) return 'icon';
+    if (basisWidth >= 24) return 'sparkline';
+    return 'bars';
+  }
+
+  /**
+   * Chooses a screenshot-like empty chart preview from generic chart protocol fields.
+   * @param block - Rendered chart block.
+   * @param data - Current chart renderer data.
+   * @returns Generic chart preview kind.
+   */
+  function imageComposeChartPreviewKind(block: WorkbenchBlock, data?: DisplayBlockData): ImageComposeChartPreviewKind {
+    const record: Record<string, unknown> = isRecord(data) ? data : {};
+    const chartType = textValue(record.chartType, textValue(block.meta?.chartType));
+    const rendererKey = chartRendererKey(block);
+    const visual = visualFor(block) as BlockVisualOptions & Record<string, unknown>;
+    const visualChart = isRecord(visual.chart) ? visual.chart : {};
+    const visualKind = textValue(
+      visual.visualKind,
+      textValue(block.meta?.visualKind, textValue(record.visualKind, textValue(visualChart.type))),
+    );
+    const seriesTypes = Array.isArray(record.series)
+      ? record.series
+        .filter(isRecord)
+        .map((series) => textValue(series.type))
+        .filter(Boolean)
+        .join(' ')
+      : '';
+    const protocol = [chartType, rendererKey, visualKind, seriesTypes].join(' ');
+    if (/pie|donut|ring|circle|doughnut/i.test(protocol)) return 'donut';
+    const wantsBar = /bar|column|histogram/i.test(protocol);
+    const wantsLine = /line|area|trend|spark/i.test(protocol);
+    if (wantsBar && !wantsLine) return 'bar';
+    if (wantsLine && !wantsBar) return 'line';
+    return 'mixed';
+  }
+
+  /**
+   * Converts unknown chart point values into finite numbers for preview graphics.
+   * @param value - Candidate chart point.
+   * @returns Finite numeric value, or undefined when unavailable.
+   */
+  function imageComposeChartPreviewNumber(value: unknown): number | undefined {
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+    if (typeof value === 'string' && value.trim()) {
+      const parsed = Number(value.replace(/,/g, '').replace(/%$/, '').trim());
+      return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    if (isRecord(value)) {
+      return imageComposeChartPreviewNumber(value.value ?? value.metric_value ?? value.count ?? value.amount);
+    }
+    return undefined;
+  }
+
+  /**
+   * Reads generic chart values from refreshed series, pie slices, rows, or source-image percentages.
+   * @param data - Current chart renderer data.
+   * @returns Numeric values for screenshot-like chart preview drawing.
+   */
+  function imageComposeChartPreviewValues(data?: DisplayBlockData): number[] {
+    const record: Record<string, unknown> = isRecord(data) ? data : {};
+    const series = Array.isArray(record.series) ? record.series.filter(isRecord) : [];
+    const firstSeriesData = series.flatMap((item) => Array.isArray(item.data) ? item.data : []);
+    const seriesValues = firstSeriesData
+      .map(imageComposeChartPreviewNumber)
+      .filter((value): value is number => value !== undefined);
+    if (seriesValues.length > 0) return seriesValues.slice(0, 8);
+    const slices = Array.isArray(record.slices) ? record.slices.filter(isRecord) : [];
+    const sliceValues = slices
+      .map((item) => imageComposeChartPreviewNumber(item.value ?? item.percent ?? item.share))
+      .filter((value): value is number => value !== undefined);
+    if (sliceValues.length > 0) return sliceValues.slice(0, 8);
+    const rows = Array.isArray(record.rows) ? record.rows.filter(isRecord) : [];
+    const rowValues = rows
+      .map((row) => Object.values(row).map(imageComposeChartPreviewNumber).find((value) => value !== undefined))
+      .filter((value): value is number => value !== undefined);
+    if (rowValues.length > 0) return rowValues.slice(0, 8);
+    const percentages = Array.isArray(record.samplePercentages) ? record.samplePercentages : [];
+    const sampleValues = percentages
+      .map(imageComposeChartPreviewNumber)
+      .filter((value): value is number => value !== undefined);
+    return sampleValues.length > 0 ? sampleValues.slice(0, 8) : [36, 48, 28, 58, 40, 66];
+  }
+
+  /**
+   * Builds SVG bar geometry from refreshed chart values while keeping the screenshot-like plot shell.
+   * @param block - Rendered chart block.
+   * @param data - Current chart renderer data.
+   * @returns Bar geometry for the compact preview SVG.
+   */
+  function imageComposeChartPreviewBars(block: WorkbenchBlock, data?: DisplayBlockData): ImageComposeChartPreviewBar[] {
+    void block;
+    const values = imageComposeChartPreviewValues(data).slice(0, 6);
+    while (values.length < IMAGE_COMPOSE_CHART_PREVIEW_MIN_BAR_COUNT) {
+      values.push(30 + values.length * 8);
+    }
+    const max = Math.max(...values.map((value) => Math.abs(value)), 1);
+    const barWidth = 24;
+    const xPositions = [30, 86, 142, 198, 254, 310];
+    return values.map((value, index) => {
+      const height = Math.max(24, Math.round(34 + (Math.abs(value) / max) * 68));
+      return {
+        x: xPositions[index] ?? (38 + index * 56),
+        y: 116 - height,
+        width: barWidth,
+        height,
+        fill: index === Math.min(3, values.length - 1) ? '#4c2cff' : '#edeff6',
+        opacity: index === Math.min(3, values.length - 1) ? 0.9 : 1,
+        label: String(value),
+      };
+    });
+  }
+
+  /**
+   * Builds a compact donut style from refreshed chart values.
+   * @param block - Rendered chart block.
+   * @param data - Current chart renderer data.
+   * @returns Inline style for the donut preview.
+   */
+  function imageComposeChartPreviewDonutStyle(block: WorkbenchBlock, data?: DisplayBlockData): Record<string, string> {
+    void block;
+    const values = imageComposeChartPreviewValues(data).slice(0, 4);
+    const total = values.reduce((sum, value) => sum + Math.max(0, Math.abs(value)), 0) || 1;
+    const colors = ['#4c2cff', '#19c7ad', '#a78bfa', '#e5e7eb'];
+    let cursor = 0;
+    const stops = values.map((value, index) => {
+      const start = cursor;
+      cursor += (Math.max(0, Math.abs(value)) / total) * 100;
+      return `${colors[index % colors.length]} ${start.toFixed(2)}% ${cursor.toFixed(2)}%`;
+    });
+    return {
+      background: `conic-gradient(${stops.join(', ')})`,
+    };
+  }
+
+  /**
+   * Reads the compact title shown above an image-composed chart preview.
+   * @param block - Rendered chart block.
+   * @param data - Current chart renderer data.
+   * @returns Screenshot-style chart label.
+   */
+  function imageComposeChartPreviewLabel(block: WorkbenchBlock, data?: DisplayBlockData): string {
+    const record: Record<string, unknown> = isRecord(data) ? data : {};
+    return textValue(record.primaryLabel)
+      || textValue(record.label)
+      || textValue(record.dimensionLabel)
+      || textValue(block.title, 'Chart');
+  }
+
+  /**
+   * Reads a generic chart summary value without claiming that query data succeeded.
+   * @param block - Rendered chart block.
+   * @param data - Current chart renderer data.
+   * @returns Metric-like value text for the screenshot preview header.
+   */
+  function imageComposeChartPreviewMetric(block: WorkbenchBlock, data?: DisplayBlockData): string {
+    const record: Record<string, unknown> = isRecord(data) ? data : {};
+    const displayValue = textValue(record.displayValue)
+      || textValue(record.primaryValue)
+      || textValue(record.value)
+      || textValue(record.total)
+      || textValue(record.summaryValue);
+    if (displayValue) return displayValue;
+    const primaryValue = Number(record.primaryValue ?? record.value ?? record.total ?? record.summaryValue);
+    if (Number.isFinite(primaryValue)) {
+      const format = textValue(record.primaryFormat, textValue(record.metricFormat, 'number'));
+      return metricSummaryDisplayValue({
+        shape: 'metricSummary',
+        primaryLabel: imageComposeChartPreviewLabel(block, data),
+        primaryFormat: format === 'currency' || format === 'percent' ? format : 'number',
+        primaryValue,
+        deltaPct: null,
+        compareLabel: '',
+        periodLabel: '',
+        sourceLabel: '',
+        secondary: [],
+      });
+    }
+    return textValue(block.subtitle) || '--';
+  }
+
+  /**
+   * Reads a generic status chip for image-composed chart previews.
+   * @param block - Rendered chart block.
+   * @param data - Current chart renderer data.
+   * @returns Status or delta text for the chart header.
+   */
+  function imageComposeChartPreviewStatus(_block: WorkbenchBlock, data?: DisplayBlockData): string {
+    const record: Record<string, unknown> = isRecord(data) ? data : {};
+    const explicit = textValue(record.status)
+      || textValue(record.statusLabel)
+      || textValue(record.deltaLabel)
+      || textValue(record.compareLabel);
+    if (explicit && explicit !== 'snapshot') return explicit;
+    const deltaPct = Number(record.deltaPct);
+    if (Number.isFinite(deltaPct)) return `${deltaPct >= 0 ? '+' : ''}${(deltaPct * 100).toFixed(1)}%`;
+    return '';
+  }
+
+  /**
+   * Builds all header fields for a generic image-composed chart preview.
+   * @param block - Rendered chart block.
+   * @param data - Current chart renderer data.
+   * @returns Compact chart preview header fields.
+   */
+  function imageComposeChartPreviewHeader(block: WorkbenchBlock, data?: DisplayBlockData): ImageComposeChartPreviewHeader {
+    return {
+      label: imageComposeChartPreviewLabel(block, data),
+      metric: imageComposeChartPreviewMetric(block, data),
+      status: imageComposeChartPreviewStatus(block, data),
+    };
+  }
+  
+  /**
+   * Checks whether an image-composed ranking/list card has no trustworthy rows but should keep a compact visual shell.
+   * @param block - Rendered list block.
+   * @param data - Current ranking renderer data.
+   * @returns True when the list came from image compose and has no reliable items.
+   */
+  function imageComposeEmptyRankingPreview(block: WorkbenchBlock, data: CategoryRankingData): boolean {
+    return imageComposeCompactCard()(block)
+      && !imageComposeAlertRankingCard()(block, data)
+      && dataBindingNeedsHumanIntervention()(block)
+      && (!Array.isArray(data.items) || data.items.length === 0);
+  }
+  
+  /**
+   * Returns a compact status label for empty image-composed list previews.
+   * @param block - Rendered list block.
+   * @param data - Ranking renderer data with optional status copied from recognition.
+   * @returns Status text shown as a chip.
+   */
+  function imageComposeEmptyRankingStatus(block: WorkbenchBlock, data: CategoryRankingData & Record<string, unknown>): string {
+    return textValue(data.status, imageComposeBusinessGapBadgeLabel()(block));
+  }
+  
+  /**
+   * Returns a short action/detail line for empty image-composed list previews.
+   * @param block - Rendered list block.
+   * @returns Stable business-input hint without claiming successful data binding.
+   */
+  function imageComposeEmptyRankingDetail(block: WorkbenchBlock): string {
+    return dataBindingNeedsHumanIntervention()(block) ? '需补充业务口径后回填' : '等待数据回填';
+  }
+  
+  /**
+   * Normalizes image-composed list rows without depending on a source-image title.
+   * @param block - Rendered list block.
+   * @param data - Current ranking renderer data.
+   * @returns Supplied rows first, otherwise neutral screenshot-density placeholders.
+   */
+  function imageComposeRankingPreviewItems(block: WorkbenchBlock, data: CategoryRankingData): Array<Record<string, unknown>> {
+    const items = Array.isArray(data.items) ? data.items.filter(isRecord) : [];
+    const fallbackItems = [
+      { label: textValue(data.dimensionLabel, textValue(block.title, 'Item 1')), valueLabel: '--', share: 0.72, tone: 'brand' },
+      { label: textValue(block.subtitle, 'Item 2'), valueLabel: '--', share: 0.54, tone: 'teal' },
+      { label: 'Item 3', valueLabel: '--', share: 0.38, tone: 'neutral' },
+    ];
+    return (items.length > 0 ? items : fallbackItems).slice(0, 4);
+  }
+
+  /**
+   * Reads the primary row label for an image-composed list preview.
+   * @param item - Ranking row record.
+   * @param index - Row index.
+   * @returns Row label text.
+   */
+  function imageComposeRankingPreviewLabel(item: Record<string, unknown>, index: number): string {
+    return textValue(item.label, textValue(item.title, textValue(item.name, `Item ${index + 1}`)));
+  }
+
+  /**
+   * Reads the secondary row detail for an image-composed list preview.
+   * @param item - Ranking row record.
+   * @returns Row detail text.
+   */
+  function imageComposeRankingPreviewDetail(item: Record<string, unknown>): string {
+    return textValue(item.badge, textValue(item.detail, textValue(item.description)));
+  }
+
+  /**
+   * Reads the value chip text for an image-composed list preview.
+   * @param item - Ranking row record.
+   * @param data - Current ranking renderer data.
+   * @returns Row value text.
+   */
+  function imageComposeRankingPreviewValue(item: Record<string, unknown>, data: CategoryRankingData): string {
+    const explicit = textValue(item.valueLabel, textValue(item.valueText));
+    if (explicit) return explicit;
+    const value = Number(item.value);
+    return Number.isFinite(value) ? formatMetricValue(value, data.valueFormat) : '--';
+  }
+
+  /**
+   * Builds an avatar label for an image-composed list preview row.
+   * @param item - Ranking row record.
+   * @param index - Row index.
+   * @returns Short avatar text.
+   */
+  function imageComposeRankingPreviewAvatar(item: Record<string, unknown>, index: number): string {
+    return textValue(item.avatar, imageComposeRankingPreviewLabel(item, index).slice(0, 1) || String(index + 1)).toUpperCase();
+  }
+
+  /**
+   * Builds avatar colors for an image-composed list preview row.
+   * @param item - Ranking row record.
+   * @param index - Row index.
+   * @returns Tailwind class list.
+   */
+  function imageComposeRankingPreviewAvatarClass(item: Record<string, unknown>, index: number): string[] {
+    const tone = textValue(item.tone, textValue(item.status));
+    const base = ['grid h-7 w-7 shrink-0 place-items-center rounded-full text-[11px] font-semibold'];
+    if (/teal|cyan|success/i.test(tone) || index === 1) return [...base, 'bg-[#e8fbf7] text-[#0f9f8b]'];
+    if (/warn|amber/i.test(tone) || index === 2) return [...base, 'bg-[#fff3d6] text-[#d78b00]'];
+    if (/danger|error|red/i.test(tone)) return [...base, 'bg-rose-50 text-rose-600'];
+    return [...base, 'bg-[#4c2cff] text-white'];
+  }
+
+  /**
+   * Builds value chip colors for an image-composed list preview row.
+   * @param item - Ranking row record.
+   * @param index - Row index.
+   * @returns Tailwind class list.
+   */
+  function imageComposeRankingPreviewValueClass(item: Record<string, unknown>, index: number): string[] {
+    const tone = textValue(item.tone, textValue(item.status));
+    const base = ['rounded-full px-2 py-0.5 text-[11px] font-semibold leading-5'];
+    if (/danger|error|red/i.test(tone)) return [...base, 'bg-rose-50 text-rose-600'];
+    if (/teal|cyan|success/i.test(tone) || index === 1) return [...base, 'bg-[#e8fbf7] text-[#0f9f8b]'];
+    if (/warn|amber/i.test(tone) || index === 2) return [...base, 'bg-[#fff3d6] text-[#d78b00]'];
+    return [...base, 'bg-[#f0efff] text-[#4c2cff]'];
+  }
+
+  function activeTabFor(block: WorkbenchBlock) {
+    return metaRecord(block, 'activeShowcaseTab');
+  }
+  
+  function tabsFor(block: WorkbenchBlock) {
+    return metaList(block, 'showcaseTabs');
+  }
+  
+  function orgMetricValues(block: WorkbenchBlock) {
+    const overview = metaRecord(block, 'showcaseOverview');
+    const activeTab = activeTabFor(block);
+    return [
+      { label: '卡片总数', value: numberValue(overview.totalCount), icon: LayoutDashboard },
+      { label: '验收卡片', value: numberValue(overview.acceptanceCount), icon: CircleCheck },
+      { label: '能力分类', value: numberValue(overview.categoryCount), icon: UserRound },
+      { label: '当前分类', value: numberValue(activeTab.count), icon: Bot },
+    ];
+  }
+  
+  function visualFor(block: WorkbenchBlock): BlockVisualOptions {
+    return block.meta?.visual || {};
+  }
+  
+  /**
+   * Returns visual metadata after removing stale high-fidelity markers that do not match the current scene.
+   * @param block - Rendered workbench block.
+   * @param data - Optional customCanvas data used for scene classification.
+   * @returns Visual metadata safe for the current renderer branch.
+   */
+  function visualForScene(block: WorkbenchBlock, data?: CustomCanvasData): BlockVisualOptions {
+    const visual = visualFor(block);
+    if (!data || visual.businessSummaryBand !== 'risk' || referenceCompositeLooksLikeChairmanRiskDirectContext()(block, data)) return visual;
+    const {
+      businessSummaryBand: _businessSummaryBand,
+      backgroundColor: _backgroundColor,
+      textColor: _textColor,
+      borderColor: _borderColor,
+      cardShadow: _cardShadow,
+      ...rest
+    } = visual;
+    return rest;
+  }
+  
+  function rowGrid(columns: string[]) {
+    return { gridTemplateColumns: `repeat(${Math.max(1, columns.length)}, minmax(0, 1fr))` };
+  }
+  
+  /**
+   * Formats metric data while preserving image-recognized static display text.
+   * @param data - Metric summary renderer data.
+   * @returns Value text for the metric card.
+   */
+  function metricSummaryDisplayValue(data: MetricSummaryData & Record<string, unknown>): string {
+    return textValue(data.displayValue)
+      || formatMetricValue(data.primaryValue, data.primaryFormat);
+  }
+  
+  /**
+   * Returns the unit text that should be shown beside an image-recognized KPI value.
+   * @param data - Metric summary renderer data.
+   * @returns Unit label when it is not already part of the visible value.
+   */
+  function metricSummaryUnitLabel(data: MetricSummaryData & Record<string, unknown>): string {
+    const displayValue = metricSummaryDisplayValue(data);
+    const unit = textValue(data.unit);
+    if (!unit || displayValue.includes(unit)) return '';
+    return unit;
+  }
+
+  /**
+   * Returns the first compact secondary metric text from image-composed KPI data.
+   * @param data - Metric summary renderer data.
+   * @returns Secondary metric formatted for the compact right-side status slot.
+   */
+  function imageComposeMetricSecondaryStatus(data: MetricSummaryData & Record<string, unknown>): string {
+    const secondary = Array.isArray(data.secondary) ? data.secondary.find(isRecord) : undefined;
+    if (!secondary) return '';
+    const label = textValue(secondary.label);
+    const value = textValue(secondary.value, String(secondary.value ?? ''));
+    if (!value) return '';
+    return label && !/^(同比|环比|变化|增长)$/u.test(label) ? `${label} ${value}` : value;
+  }
+  
+  /**
+   * Reads the screenshot footer summary for image-composed KPI cards.
+   * @param data - Metric summary renderer data.
+   * @returns Footer text recognized from the source screenshot.
+   */
+  function imageComposeMetricSubText(data: MetricSummaryData & Record<string, unknown>): string {
+    return textValue(data.subText)
+      || textValue(data.footerText)
+      || textValue(data.description)
+      || textValue(data.secondaryLabel)
+      || textValue(data.primaryLabel);
+  }
+  
+  /**
+   * Extracts the compact right-side status from a KPI footer.
+   * @param data - Metric summary renderer data.
+   * @returns Status token such as 达标, 可控, 需处理, or a signed delta.
+   */
+  function imageComposeMetricFooterStatus(data: MetricSummaryData & Record<string, unknown>): string {
+    const secondaryStatus = imageComposeMetricSecondaryStatus(data);
+    if (secondaryStatus) return secondaryStatus;
+    const footer = imageComposeMetricSubText(data);
+    const tokens = footer.split(/\s+/).filter(Boolean);
+    const candidate = tokens[tokens.length - 1] || '';
+    if (/^(达标|可控|需处理|告警|卡顿|延期|通过|已归档)$/u.test(candidate)) return candidate;
+    if (/^[+-]\d+(?:\.\d+)?%?$/u.test(candidate)) return candidate;
+    return '';
+  }
+  
+  /**
+   * Returns the left-side KPI footer text after removing the compact status token.
+   * @param data - Metric summary renderer data.
+   * @returns Main footer text for the KPI card.
+   */
+  function imageComposeMetricFooterMain(data: MetricSummaryData & Record<string, unknown>): string {
+    const footer = imageComposeMetricSubText(data);
+    if (imageComposeMetricSecondaryStatus(data)) return footer;
+    const status = imageComposeMetricFooterStatus(data);
+    return status ? footer.slice(0, Math.max(0, footer.length - status.length)).trim() : footer;
+  }
+  
+  /**
+   * Builds the color classes for the compact KPI footer status.
+   * @param status - Status token extracted from the screenshot footer.
+   * @returns Tailwind classes for the status text.
+   */
+  function imageComposeMetricFooterStatusClass(status: string): string[] {
+    if (/^-/.test(status)) return ['text-red-600'];
+    if (/^\+|ROI/i.test(status)) return ['text-emerald-700'];
+    if (/需处理|告警|卡顿|延期|^\+/.test(status)) return ['text-red-600'];
+    if (/^-|达标|可控|通过|已归档/.test(status)) return ['text-emerald-700'];
+    return ['text-slate-600'];
+  }
+  
+  /**
+   * Builds the dot color for compact image-composed KPI headers.
+   * @param status - Status token extracted from the screenshot footer.
+   * @returns Tailwind classes for the small status dot.
+   */
+  function imageComposeMetricStatusDotClass(status: string): string[] {
+    if (/^-/.test(status)) return ['bg-red-600'];
+    if (/^\+|ROI/i.test(status)) return ['bg-emerald-600'];
+    if (/需处理|告警|卡顿|延期|^\+/.test(status)) return ['bg-red-600'];
+    if (/^-|达标|可控|通过|已归档/.test(status)) return ['bg-emerald-600'];
+    return ['bg-amber-600'];
+  }
+  
+  function chartRendererKey(block: WorkbenchBlock) {
+    return block.renderer?.rendererKey || String(block.subType || '');
+  }
+  
+
+  return {
+    isFormBlockData,
+    isSurveyBlockData,
+    isActionGroupData,
+    isWorkflowBlockData,
+    isReportBlockData,
+    textValue,
+    numberValue,
+    listValue,
+    metaRecord,
+    metaList,
+    welcomeBannerMetrics,
+    tierKeyForDensity,
+    applyResponsiveTier,
+    formValues,
+    surveyAnswers,
+    compactLimit,
+    toggleMultiValue,
+    formCompletedCount,
+    renderFieldType,
+    updateMatrixAnswer,
+    matrixAnswerValue,
+    multipleAnswerIncludes,
+    taskStatusClass,
+    taskTypeLabel,
+    taskStatusLabel,
+    tableRowsPreviewVisualKind,
+    tableRowsPreviewCard,
+    tableRowsPreviewRecords,
+    tableRowsPreviewCell,
+    tableRowsTimelinePrimaryCell,
+    tableRowsTimelineBadgeCell,
+    tableRowsPreviewGridStyle,
+    formatWeatherTemp,
+    weatherIcon,
+    isChartShape,
+    imageComposeEmptyChartPreview,
+    imageComposeChartPreview,
+    imageComposeMetricLeadingVisualKind,
+    imageComposeChartPreviewKind,
+    imageComposeChartPreviewLabel,
+    imageComposeChartPreviewMetric,
+    imageComposeChartPreviewStatus,
+    imageComposeChartPreviewHeader,
+    imageComposeChartPreviewBars,
+    imageComposeChartPreviewDonutStyle,
+    imageComposeEmptyRankingPreview,
+    imageComposeEmptyRankingStatus,
+    imageComposeEmptyRankingDetail,
+    imageComposeRankingPreviewItems,
+    imageComposeRankingPreviewLabel,
+    imageComposeRankingPreviewDetail,
+    imageComposeRankingPreviewValue,
+    imageComposeRankingPreviewAvatar,
+    imageComposeRankingPreviewAvatarClass,
+    imageComposeRankingPreviewValueClass,
+    activeTabFor,
+    tabsFor,
+    orgMetricValues,
+    visualFor,
+    visualForScene,
+    rowGrid,
+    tableColumnsFromRows,
+    tableRowCells,
+    metricSummaryDisplayValue,
+    metricSummaryUnitLabel,
+    imageComposeMetricSubText,
+    imageComposeMetricFooterStatus,
+    imageComposeMetricFooterMain,
+    imageComposeMetricFooterStatusClass,
+    imageComposeMetricStatusDotClass,
+    chartRendererKey,
+  };
+}