@archbase/components 3.0.25 → 4.0.1

package/src/editors/ArchbaseSpreadsheet.tsx

@@ -0,0 +1,388 @@
+/**
+ * ArchbaseSpreadsheet — wrapper para fortune-sheet integrado ao DataSource.
+ * Permite exibir e editar dados tabulares em formato de planilha.
+ * @status experimental
+ */
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import type { CSSProperties } from 'react';
+import { Box, Input } from '@mantine/core';
+import { useForceUpdate } from '@mantine/hooks';
+import { Workbook } from '@fortune-sheet/react';
+import '@fortune-sheet/react/dist/index.css';
+import type { DataSourceEvent, IArchbaseDataSourceBase } from '@archbase/data';
+import { DataSourceEventNames, useArchbaseDataSourceListener } from '@archbase/data';
+
+// ─────────────────────────── Types ───────────────────────────
+
+export type ArchbaseColumnType = 'text' | 'number' | 'date' | 'boolean' | 'currency';
+
+export interface ArchbaseColumnDef<T> {
+  /** Campo do registro mapeado para esta coluna */
+  field: keyof T | string;
+  /** Cabeçalho exibido na planilha */
+  header: string;
+  /** Largura da coluna em pixels */
+  width?: number;
+  /** Tipo do dado */
+  type?: ArchbaseColumnType;
+  /** Formato numérico (ex: '#,##0.00') */
+  format?: string;
+  /** Se a coluna é editável */
+  editable?: boolean;
+}
+
+export interface ArchbaseSpreadsheetProps<T, ID> {
+  /** Fonte de dados que fornece os registros */
+  dataSource?: IArchbaseDataSourceBase<T>;
+  /** Definição de colunas para mapeamento DataSource -> planilha */
+  columns?: ArchbaseColumnDef<T>[];
+  /** Dados standalone no formato Sheet[] do fortune-sheet */
+  data?: any[];
+  /** Permite edição (default: true) */
+  editable?: boolean;
+  /** Exibe a toolbar (default: true) */
+  showToolbar?: boolean;
+  /** Exibe a barra de fórmulas (default: true) */
+  showFormulaBar?: boolean;
+  /** Exibe as abas de planilhas (default: true) */
+  showSheetTabs?: boolean;
+  /** Altura do componente */
+  height?: string | number;
+  /** Largura do componente */
+  width?: string | number;
+  /** Callback quando uma célula é alterada */
+  onCellChange?: (row: number, col: number, oldValue: any, newValue: any) => void;
+  /** Callback quando a seleção muda */
+  onSelectionChange?: (ranges: any[]) => void;
+  /** Rótulo (Input.Wrapper) */
+  label?: string;
+  /** Descrição (Input.Wrapper) */
+  description?: string;
+  /** Somente leitura */
+  readOnly?: boolean;
+  /** Locale (default: 'pt-BR') */
+  locale?: string;
+  /** Estilo adicional do container */
+  style?: CSSProperties;
+  /** Classe CSS adicional */
+  className?: string;
+}
+
+// ─────────────────────── Helpers ─────────────────────────
+
+/** Retorna o valor de um campo possivelmente aninhado (notacao de ponto) */
+function getNestedValue(obj: any, path: string): any {
+  if (!obj || !path) return undefined;
+  return path.split('.').reduce((acc, part) => acc?.[part], obj);
+}
+
+/** Mapeia ArchbaseColumnType para o cell type do fortune-sheet */
+function mapColumnTypeToCellType(type?: ArchbaseColumnType): number {
+  switch (type) {
+    case 'number':
+    case 'currency':
+      return 0; // number
+    case 'boolean':
+      return 0; // tratado como number (0/1)
+    case 'date':
+      return 0; // date stored as number in sheets
+    case 'text':
+    default:
+      return 1; // string
+  }
+}
+
+/** Converte valor do DataSource para valor da célula */
+function toCellValue(value: any, type?: ArchbaseColumnType): any {
+  if (value === null || value === undefined) return '';
+  switch (type) {
+    case 'boolean':
+      return value ? 1 : 0;
+    case 'number':
+    case 'currency':
+      return typeof value === 'number' ? value : Number(value) || 0;
+    default:
+      return String(value);
+  }
+}
+
+/** Converte valor da célula de volta para o tipo esperado pelo DataSource */
+function fromCellValue(value: any, type?: ArchbaseColumnType): any {
+  if (value === '' || value === null || value === undefined) return null;
+  switch (type) {
+    case 'boolean':
+      return Boolean(Number(value));
+    case 'number':
+    case 'currency':
+      return Number(value);
+    default:
+      return String(value);
+  }
+}
+
+// ─────────────────────── Conversao DS -> Sheet ───────────────────────
+
+function buildSheetFromDataSource<T>(
+  dataSource: IArchbaseDataSourceBase<T>,
+  columns: ArchbaseColumnDef<T>[],
+): any {
+  const records = dataSource.browseRecords();
+  const celldata: any[] = [];
+
+  // Header row
+  columns.forEach((col, colIdx) => {
+    celldata.push({
+      r: 0,
+      c: colIdx,
+      v: {
+        v: col.header,
+        ct: { fa: 'General', t: 's' },
+        m: col.header,
+        bl: 1, // bold
+      },
+    });
+  });
+
+  // Data rows
+  records.forEach((record, rowIdx) => {
+    columns.forEach((col, colIdx) => {
+      const raw = getNestedValue(record, String(col.field));
+      const value = toCellValue(raw, col.type);
+      const ct =
+        col.type === 'number' || col.type === 'currency'
+          ? { fa: col.format || 'General', t: 'n' }
+          : { fa: 'General', t: 's' };
+
+      celldata.push({
+        r: rowIdx + 1, // +1 for header
+        c: colIdx,
+        v: {
+          v: value,
+          ct,
+          m: String(value),
+        },
+      });
+    });
+  });
+
+  // Column widths
+  const columnlen: Record<number, number> = {};
+  columns.forEach((col, idx) => {
+    columnlen[idx] = col.width ?? 100;
+  });
+
+  return {
+    name: 'Sheet1',
+    index: '0',
+    status: 1,
+    order: 0,
+    celldata,
+    column: columns.length,
+    row: records.length + 1,
+    config: {
+      columnlen,
+    },
+  };
+}
+
+// ─────────────────────── Componente ─────────────────────────
+
+function ArchbaseSpreadsheetInner<T, ID>(
+  props: ArchbaseSpreadsheetProps<T, ID>,
+) {
+  const {
+    dataSource,
+    columns,
+    data: externalData,
+    editable = true,
+    showToolbar = true,
+    showFormulaBar = true,
+    showSheetTabs = true,
+    height = '400px',
+    width = '100%',
+    onCellChange,
+    onSelectionChange,
+    label,
+    description,
+    readOnly = false,
+    locale = 'pt-BR',
+    style,
+    className,
+  } = props;
+
+  const forceUpdate = useForceUpdate();
+  const prevCellDataRef = useRef<Map<string, any>>(new Map());
+
+  // ── Construir dados da planilha ──
+
+  const sheetData = useMemo(() => {
+    if (externalData && externalData.length > 0) {
+      return externalData;
+    }
+    if (dataSource && columns && columns.length > 0) {
+      return [buildSheetFromDataSource(dataSource, columns)];
+    }
+    return [
+      {
+        name: 'Sheet1',
+        index: '0',
+        status: 1,
+        order: 0,
+        celldata: [],
+        column: 10,
+        row: 30,
+      },
+    ];
+  }, [externalData, dataSource, columns]);
+
+  // ── Guardar referencia a valores anteriores para detectar mudancas ──
+
+  useEffect(() => {
+    const map = new Map<string, any>();
+    if (sheetData && sheetData.length > 0) {
+      const sheet = sheetData[0];
+      if (sheet.celldata) {
+        for (const cell of sheet.celldata) {
+          map.set(`${cell.r}_${cell.c}`, cell.v?.v);
+        }
+      }
+    }
+    prevCellDataRef.current = map;
+  }, [sheetData]);
+
+  // ── Listener do DataSource ──
+
+  const handleDataSourceEvent = useCallback(
+    (event: DataSourceEvent<T>) => {
+      switch (event.type) {
+        case DataSourceEventNames.dataChanged:
+        case DataSourceEventNames.recordChanged:
+        case DataSourceEventNames.refreshData:
+        case DataSourceEventNames.afterInsert:
+        case DataSourceEventNames.afterRemove:
+        case DataSourceEventNames.afterCancel:
+        case DataSourceEventNames.afterSave:
+        case DataSourceEventNames.afterEdit:
+          forceUpdate();
+          break;
+      }
+    },
+    [forceUpdate],
+  );
+
+  if (dataSource) {
+    useArchbaseDataSourceListener<T>({
+      dataSource,
+      listener: handleDataSourceEvent,
+    });
+  }
+
+  // ── Handlers fortune-sheet ──
+
+  const handleCellUpdated = useCallback(
+    (row: number, col: number, newValue: any) => {
+      const key = `${row}_${col}`;
+      const oldValue = prevCellDataRef.current.get(key);
+      prevCellDataRef.current.set(key, newValue);
+
+      // Callback externo
+      onCellChange?.(row, col, oldValue, newValue);
+
+      // Atualizar DataSource se em modo de edicao
+      if (dataSource && columns && columns.length > 0 && row > 0) {
+        const recordIndex = row - 1; // header na linha 0
+        const colDef = columns[col];
+        if (colDef && colDef.editable !== false) {
+          const records = dataSource.browseRecords();
+          if (recordIndex >= 0 && recordIndex < records.length) {
+            // Navegar para o registro correspondente
+            if (dataSource.getCurrentIndex() !== recordIndex) {
+              dataSource.gotoRecord(recordIndex);
+            }
+            if (dataSource.isEditing() || dataSource.isInserting()) {
+              const converted = fromCellValue(newValue, colDef.type);
+              dataSource.setFieldValue(String(colDef.field), converted);
+            }
+          }
+        }
+      }
+    },
+    [dataSource, columns, onCellChange],
+  );
+
+  // ── Fortune-sheet onChange handler ──
+
+  const handleChange = useCallback(
+    (data: any[]) => {
+      // fortune-sheet dispara onChange com os dados atualizados
+      // Detectar mudancas de celula comparando com o estado anterior
+      if (data && data.length > 0) {
+        const sheet = data[0];
+        if (sheet?.celldata) {
+          for (const cell of sheet.celldata) {
+            const key = `${cell.r}_${cell.c}`;
+            const prev = prevCellDataRef.current.get(key);
+            const cur = cell.v?.v;
+            if (prev !== cur) {
+              handleCellUpdated(cell.r, cell.c, cur);
+            }
+          }
+        }
+      }
+    },
+    [handleCellUpdated],
+  );
+
+  // ── Locale mapping ──
+
+  const lang = useMemo(() => {
+    if (locale?.startsWith('pt')) return 'pt-BR' as const;
+    if (locale?.startsWith('es')) return 'es' as const;
+    if (locale?.startsWith('zh')) return 'zh' as const;
+    return 'en' as const;
+  }, [locale]);
+
+  // ── Computed height ──
+
+  const computedHeight = typeof height === 'number' ? `${height}px` : height;
+  const computedWidth = typeof width === 'number' ? `${width}px` : width;
+
+  // ── Render ──
+
+  const spreadsheetContent = (
+    <Box
+      className={className}
+      style={{
+        height: computedHeight,
+        width: computedWidth,
+        position: 'relative',
+        overflow: 'hidden',
+        ...style,
+      }}
+    >
+      <Workbook
+        data={sheetData}
+        onChange={handleChange}
+        allowEdit={editable && !readOnly}
+        showToolbar={showToolbar}
+        showFormulaBar={showFormulaBar}
+        showSheetTabs={showSheetTabs}
+        lang={lang}
+      />
+    </Box>
+  );
+
+  if (label || description) {
+    return (
+      <Input.Wrapper label={label} description={description}>
+        {spreadsheetContent}
+      </Input.Wrapper>
+    );
+  }
+
+  return spreadsheetContent;
+}
+
+export const ArchbaseSpreadsheet = React.memo(ArchbaseSpreadsheetInner) as typeof ArchbaseSpreadsheetInner;
+
+(ArchbaseSpreadsheet as any).displayName = 'ArchbaseSpreadsheet';

package/src/editors/ArchbaseTagInput.tsx

@@ -0,0 +1,326 @@
+/**
+ * ArchbaseTagInput — editor de tags integrado ao DataSource (v1/v2) com suporte a validacao e estado controlado.
+ * Utiliza o componente TagsInput do Mantine internamente.
+ * @status stable
+ */
+import { MantineSize, TagsInput } from '@mantine/core';
+import { useForceUpdate } from '@mantine/hooks';
+import type { CSSProperties, FocusEventHandler } from 'react';
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import type { DataSourceEvent, IArchbaseDataSourceBase } from '@archbase/data';
+import { DataSourceEventNames, useArchbaseDidUpdate, useArchbaseV1V2Compatibility } from '@archbase/data';
+import { useValidationErrors } from '@archbase/core';
+
+export interface ArchbaseTagInputProps<T, ID> {
+	/** Fonte de dados onde sera atribuido o valor das tags (V1 ou V2) */
+	dataSource?: IArchbaseDataSourceBase<T>;
+	/** Campo onde devera ser atribuido o valor das tags na fonte de dados */
+	dataField?: string;
+	/** Valor controlado (array de strings) quando usado sem dataSource */
+	value?: string[];
+	/** Valor padrao inicial (array de strings) */
+	defaultValue?: string[];
+	/** Delimitador usado para serializar/deserializar quando o campo no dataSource e uma string. Padrao: ',' */
+	delimiter?: string;
+	/** Titulo do campo */
+	label?: string;
+	/** Descricao do campo */
+	description?: string;
+	/** Ultimo erro ocorrido no campo */
+	error?: string;
+	/** Texto sugestao do campo */
+	placeholder?: string;
+	/** Indicador se o preenchimento e obrigatorio */
+	required?: boolean;
+	/** Indicador se o campo esta desabilitado */
+	disabled?: boolean;
+	/** Indicador se o campo e somente leitura. Obs: usado em conjunto com o status da fonte de dados */
+	readOnly?: boolean;
+	/** Lista de caracteres que, ao serem digitados, criam uma nova tag. Ex: [',', ' ', 'Enter'] */
+	separators?: string[];
+	/** Numero maximo de tags permitidas */
+	maxTags?: number;
+	/** Permite tags duplicadas */
+	allowDuplicates?: boolean;
+	/** Evento quando o valor das tags e alterado */
+	onChangeValue?: (value: string[], event?: any) => void;
+	/** Evento quando o campo recebe o foco */
+	onFocusEnter?: FocusEventHandler<HTMLInputElement>;
+	/** Evento quando o foco sai do campo */
+	onFocusExit?: FocusEventHandler<HTMLInputElement>;
+	/** Referencia para o componente interno */
+	innerRef?: React.RefObject<HTMLInputElement>;
+	/** Estilo do campo */
+	style?: CSSProperties;
+	/** Classe CSS adicional */
+	className?: string;
+	/** Largura do campo */
+	width?: string | number;
+	/** Tamanho do campo (Mantine size) */
+	size?: MantineSize;
+}
+
+export function ArchbaseTagInput<T, ID>({
+	dataSource,
+	dataField,
+	value: valueProp,
+	defaultValue,
+	delimiter = ',',
+	label,
+	description,
+	error,
+	placeholder,
+	required = false,
+	disabled = false,
+	readOnly = false,
+	separators,
+	maxTags,
+	allowDuplicates = false,
+	onChangeValue = () => {},
+	onFocusEnter = () => {},
+	onFocusExit = () => {},
+	innerRef,
+	style,
+	className,
+	width,
+	size,
+}: ArchbaseTagInputProps<T, ID>) {
+	// Hook de compatibilidade V1/V2
+	const v1v2Compatibility = useArchbaseV1V2Compatibility<string[]>(
+		'ArchbaseTagInput',
+		dataSource,
+		dataField,
+		[],
+	);
+
+	const [tags, setTags] = useState<string[]>(valueProp || defaultValue || []);
+	const innerComponentRef = useRef<any>(null);
+	const [internalError, setInternalError] = useState<string | undefined>(error);
+	const forceUpdate = useForceUpdate();
+	/** Guarda se o valor original no dataSource e uma string (para serializar de volta) */
+	const originalIsStringRef = useRef<boolean>(false);
+
+	// Contexto de validacao (opcional - pode nao existir)
+	const validationContext = useValidationErrors();
+
+	// Chave unica para o field
+	const fieldKey = `${dataField}`;
+
+	// Recuperar erro do contexto se existir
+	const contextError = validationContext?.getError(fieldKey);
+
+	// Atualizar erro externo
+	useEffect(() => {
+		if (error !== undefined && error !== internalError) {
+			setInternalError(error);
+		}
+	}, [error]);
+
+	/**
+	 * Converte o valor bruto do campo do dataSource em um array de strings.
+	 * Se o valor for uma string, faz split pelo delimiter.
+	 * Se for um array, usa diretamente.
+	 */
+	const parseFieldValue = (raw: any): string[] => {
+		if (raw === null || raw === undefined || raw === '') {
+			return [];
+		}
+		if (Array.isArray(raw)) {
+			originalIsStringRef.current = false;
+			return raw.map(String);
+		}
+		if (typeof raw === 'string') {
+			originalIsStringRef.current = true;
+			return raw
+				.split(delimiter)
+				.map((s) => s.trim())
+				.filter((s) => s.length > 0);
+		}
+		return [];
+	};
+
+	/**
+	 * Serializa o array de tags de volta para o formato original do campo no dataSource.
+	 * Se o campo original era string, junta pelo delimiter; se era array, mantem como array.
+	 */
+	const serializeValue = (tagsArray: string[]): string | string[] => {
+		if (originalIsStringRef.current) {
+			return tagsArray.join(delimiter);
+		}
+		return tagsArray;
+	};
+
+	const loadDataSourceFieldValue = () => {
+		let initialValue: string[] = valueProp || defaultValue || [];
+
+		if (dataSource && dataField) {
+			const raw = dataSource.getFieldValue(dataField);
+			initialValue = parseFieldValue(raw);
+		}
+
+		setTags(initialValue);
+	};
+
+	const fieldChangedListener = useCallback(() => {
+		loadDataSourceFieldValue();
+	}, []);
+
+	const dataSourceEvent = useCallback(
+		(event: DataSourceEvent<T>) => {
+			if (dataSource && dataField) {
+				if (
+					event.type === DataSourceEventNames.dataChanged ||
+					event.type === DataSourceEventNames.recordChanged ||
+					event.type === DataSourceEventNames.afterScroll ||
+					event.type === DataSourceEventNames.afterCancel ||
+					event.type === DataSourceEventNames.afterEdit ||
+					event.type === DataSourceEventNames.afterInsert
+				) {
+					loadDataSourceFieldValue();
+					if (!v1v2Compatibility.isDataSourceV2) {
+						forceUpdate();
+					}
+				}
+
+				// Limpa erros em eventos de edicao/cancelamento
+				if (
+					event.type === DataSourceEventNames.afterEdit ||
+					event.type === DataSourceEventNames.afterInsert ||
+					event.type === DataSourceEventNames.afterCancel
+				) {
+					setInternalError(undefined);
+					validationContext?.clearError(fieldKey);
+				}
+
+				if (
+					event.type === DataSourceEventNames.onFieldError &&
+					event.fieldName === dataField
+				) {
+					setInternalError(event.error);
+					validationContext?.setError(fieldKey, event.error);
+					if (!v1v2Compatibility.isDataSourceV2) {
+						forceUpdate();
+					}
+				}
+			}
+		},
+		[
+			v1v2Compatibility.isDataSourceV2,
+			dataSource,
+			dataField,
+			loadDataSourceFieldValue,
+			forceUpdate,
+			validationContext,
+			fieldKey,
+		],
+	);
+
+	// Ref para manter callback sempre atualizado (corrige problema de closure desatualizada)
+	const dataSourceEventRef = useRef(dataSourceEvent);
+	useEffect(() => {
+		dataSourceEventRef.current = dataSourceEvent;
+	}, [dataSourceEvent]);
+
+	// Wrapper estavel que delega para ref - nunca muda, entao o listener permanece consistente
+	const stableDataSourceEvent = useCallback((event: DataSourceEvent<T>) => {
+		dataSourceEventRef.current(event);
+	}, []);
+
+	// Registrar listeners com cleanup apropriado
+	useEffect(() => {
+		loadDataSourceFieldValue();
+		if (dataSource && dataField) {
+			const hasFieldListener =
+				typeof (dataSource as any).addFieldChangeListener === 'function';
+			dataSource.addListener(stableDataSourceEvent);
+			if (hasFieldListener) {
+				(dataSource as any).addFieldChangeListener(dataField, fieldChangedListener);
+			}
+
+			return () => {
+				dataSource.removeListener(stableDataSourceEvent);
+				if (hasFieldListener) {
+					(dataSource as any).removeFieldChangeListener(
+						dataField,
+						fieldChangedListener,
+					);
+				}
+			};
+		}
+	}, [dataSource, dataField, stableDataSourceEvent, fieldChangedListener]);
+
+	useArchbaseDidUpdate(() => {
+		loadDataSourceFieldValue();
+	}, []);
+
+	const handleChange = (newTags: string[]) => {
+		// Limpa erro quando usuario edita o campo
+		const hasError = internalError || contextError;
+		if (hasError) {
+			setInternalError(undefined);
+			validationContext?.clearError(fieldKey);
+		}
+
+		setTags(newTags);
+
+		if (
+			dataSource &&
+			!dataSource.isBrowsing() &&
+			dataField
+		) {
+			const serialized = serializeValue(newTags);
+			v1v2Compatibility.handleValueChange(serialized as any);
+		}
+
+		if (onChangeValue) {
+			onChangeValue(newTags);
+		}
+	};
+
+	const handleOnFocusExit = (event: React.FocusEvent<HTMLInputElement>) => {
+		if (onFocusExit) {
+			onFocusExit(event);
+		}
+	};
+
+	const handleOnFocusEnter = (event: React.FocusEvent<HTMLInputElement>) => {
+		if (onFocusEnter) {
+			onFocusEnter(event);
+		}
+	};
+
+	const isReadOnly = (): boolean => {
+		return readOnly || v1v2Compatibility.isReadOnly;
+	};
+
+	// Erro a ser exibido: local ou do contexto
+	const displayError = internalError || contextError;
+
+	return (
+		<TagsInput
+			value={tags}
+			onChange={handleChange}
+			label={label}
+			description={description}
+			error={displayError}
+			placeholder={placeholder}
+			required={required}
+			disabled={disabled}
+			readOnly={isReadOnly()}
+			size={size}
+			className={className}
+			maxTags={maxTags}
+			allowDuplicates={allowDuplicates}
+			splitChars={separators}
+			ref={innerRef || innerComponentRef}
+			onFocus={handleOnFocusEnter}
+			onBlur={handleOnFocusExit}
+			style={{
+				width,
+				...style,
+			}}
+		/>
+	);
+}
+
+ArchbaseTagInput.displayName = 'ArchbaseTagInput';