@ticatec/batch-data-uploader 0.0.4 → 0.0.9

package/documents/BaseTemplate_cn.md

@@ -0,0 +1,225 @@
+# BaseTemplate 类
+
+一个用于解析 Excel 文件并处理具有可定制列定义数据的抽象基类。
+
+## 概述
+
+`BaseTemplate` 类为使用 `xlsx` 库处理 Excel 文件提供了一个基础。它支持将 Excel 数据解析为结构化格式，并通过子类化支持自定义列定义和数据转换。该类设计为可扩展以适应特定用例。
+通常不需要直接从BaseTemplate继承，根据业务需要可以直接使用两个子类 `BaseEncodingTemplate` 或者 `BaseUploadTemplate`
+
+## 使用方法
+
+要使用 `BaseTemplate`，需继承该类并实现必要的自定义数据处理逻辑。以下是一个示例：
+
+```typescript
+import BaseTemplate from './BaseTemplate';
+import type { DataColumn } from './DataColumn';
+
+class MyTemplate extends BaseTemplate {
+    constructor(columns: DataColumn[], rowOffset: number = 1) {
+        super(columns, rowOffset);
+    }
+
+    // 可选地重写 consolidateData 以进行自定义数据处理
+    protected async consolidateData(rows: Array<any>): Promise<Array<any>> {
+        // 在此添加自定义逻辑
+        return rows;
+    }
+}
+```
+
+### 解析 Excel 文件
+
+要解析 Excel 文件，请使用 `File` 对象调用 `parseExcelFile` 方法：
+
+```typescript
+const file: File = // ... 获取文件（例如，从输入元素获取）
+const columns: DataColumn[] = [
+    { field: 'name', parser: (value) => String(value) },
+    { field: 'age', parser: (value) => Number(value) }
+];
+const template = new MyTemplate(columns);
+await template.parseExcelFile(file);
+console.log(template.list); // 访问解析后的数据
+```
+
+## 类详情
+
+### 构造函数
+
+```typescript
+protected constructor(columns: Array<DataColumn>, rowOffset: number = 1)
+```
+
+- **参数**：
+    - `columns`：定义数据结构（字段名和可选解析器）的 `DataColumn` 对象数组。
+    - `rowOffset`：Excel 表中要跳过的起始行数（默认值：1，例如跳过标题行）。
+- **描述**：使用列定义和行偏移初始化模板。
+
+### 方法
+
+#### `parseExcelFile`
+
+```typescript
+async parseExcelFile(file: File): Promise<void>
+```
+
+- **参数**：
+    - `file`：要解析的 Excel 文件。
+- **描述**：读取并解析 Excel 文件，根据列定义处理每一行，并将结果在应用 `consolidateData` 后存储到内部 `_list` 中。
+- **依赖**：使用 `xlsx` 读取 Excel 文件，使用 `utils` 进行嵌套值操作。
+
+#### `consolidateData`
+
+```typescript
+protected async consolidateData(rows: Array<any>): Promise<Array<any>>
+```
+
+- **参数**：
+    - `rows`：从 Excel 文件解析出的原始行对象数组。
+- **描述**：子类可重写的钩子方法，用于执行额外的数据处理。默认返回未更改的行。
+- **重写**：子类可重写此方法以实现自定义数据转换逻辑。
+
+#### `extractData`
+
+```typescript
+protected extractData(arr: Array<any>): Array<any>
+```
+
+- **参数**：
+    - `arr`：要处理的数据对象数组。
+- **描述**：过滤并映射输入数据，仅包括可见且未忽略的列，返
+  回处理后的新对象数组。
+- **用途**：在内部用于准备上传或进一步处理的数据。
+
+#### `wrapData`
+
+```typescript
+protected wrapData(data: any): any
+```
+
+- **参数**：
+    - `data`：单个行对象。
+- **描述**：用于包装或转换单个行数据的钩子方法。默认返回未更改的数据。
+- **重写**：子类可重写此方法以将数据包装为特定结构。
+
+#### `columns`（获取器）
+
+```typescript
+get columns(): Array<TableColumn>
+```
+
+- **返回**：`TableColumn` 对象的数组，表示列定义。
+- **描述**：提供列定义的副本，供数据表或其他 UI 组件使用。
+
+#### `list`（获取器）
+
+```typescript
+get list(): Array<any>
+```
+
+- **返回**：解析并处理后的数据列表的副本。
+- **描述**：提供对处理后数据的外部访问。
+
+## 类型 DataColumn接口
+
+定义数据表列结构和行为的 TypeScript 接口，用于描述数据列的元数据，支持列显示、数据解析和格式化等功能。
+`DataColumn` 接口定义了数据表中列的属性和行为，包括列标题、字段映射、格式化、对齐, 用于数据解析和上传控制的特定字段。适用于需要处理表格数据和 Excel 文件解析的场景。
+
+### 使用方法
+
+`DataColumn` 接口用于定义数据表的列结构，通常与 `BaseTemplate` 或其派生类（如 `BaseUploadTemplate`、`BaseEncodingTemplate`）结合使用。以下是一个示例：
+
+```typescript
+import type { DataColumn } from './DataColumn';
+
+const columns: DataColumn[] = [
+    {
+        field: 'user.name',
+        text: '姓名',
+        width: 150,
+        align: 'left',
+        parser: (value) => String(value).trim(),
+        visible: true,
+        ignore: false
+    },
+    {
+        field: 'user.age',
+        text: '年龄',
+        width: 100,
+        align: 'center',
+        parser: (value) => Number(value) || 0,
+        visible: true,
+        ignore: false,
+        formatter: (row) => `${row['user.age']} 岁`
+    }
+];
+```
+
+### 属性
+
+- **field**: `string`
+  - 字段名，用于映射数据对象中的属性，支持点分隔的嵌套路径（如 `user.name`）。
+- **text**: `string`
+  - 列标题文字，显示在数据表头。
+- **frozen?**: `boolean`
+  - 是否冻结列（固定在表格左侧），仅在前面列的 `frozen` 为 `true` 时有效。
+- **align?**: `'left' | 'center' | 'right'`
+  - 单元格内容对齐方式，默认为未指定（由渲染器决定）。
+- **width**: `number`
+  - 列宽度（像素）。
+- **minWidth?**: `number`
+  - 列最小宽度（像素，可选）。
+- **formatter?**: `FormatCell`
+  - 单元格格式化函数，用于自定义单元格显示内容。
+- **escapeHTML?**: `boolean`
+  - 是否转义 HTML 字符，防止 XSS 攻击（默认：未指定）。
+- **visible?**: `boolean`
+  - 列是否可见，控制是否在表格中显示（默认：未指定）。
+- **resizable?**: `boolean`
+  - 列是否允许调整宽度（默认：未指定）。
+- **ignore?**: `boolean`
+  - 是否忽略该列，设置为 `true` 时，列仅用于前端显示，不参与数据上传（默认：`false`）。
+- **parser?**: `ParserText`
+  - 数据解析函数，定义为 `(text: string) => any`，用于将 Excel 单元格的原始值转换为目标格式（例如，将字符串转换为数字）。
+
+#### 类型
+
+- **ParserText**: `(text: string) => any`
+  - 解析函数类型，接收字符串输入并返回任意类型的值，用于处理 Excel 文件中的单元格数据。
+- **FormatCell**: 自定义类型（定义在 `./FormatCell`），用于格式化单元格显示内容。
+
+
+#### 注意事项
+
+- `field` 在 `DataColumn` 中为必填属性，用于确保数据映射的正确性。
+- `parser` 函数是处理 Excel 数据时的关键，需根据字段类型（如字符串、数字、日期）定义合适的解析逻辑。
+- `ignore` 属性适用于需要在前端显示但不参与上传的列（例如，辅助信息列）。
+- 确保依赖的类型（`FormatCell`）已正确定义并导入。
+
+
+#### 示例列定义
+
+```typescript
+const columns: DataColumn[] = [
+    {
+        field: 'user.name',
+        parser: (value) => String(value).trim(),
+        visible: true,
+        ignore: false
+    },
+    {
+        field: 'user.age',
+        parser: (value) => Number(value) || 0,
+        visible: true,
+        ignore: false
+    }
+];
+```
+
+## 注意事项
+
+- 该类为抽象类，必须继承后使用。
+- 确保已安装并配置 `xlsx` 和 `@ticatec/uniface-element/DataTable`。
+- `rowOffset` 可用于跳过 Excel 文件中的标题行。
+- `DataColumn` 中的 `parser` 函数允许自定义单元格值的解析（例如，将字符串转换为数字）。

package/documents/BaseUploadTemplate.md

@@ -0,0 +1,170 @@
+# BaseUploadTemplate Class
+
+An abstract base class for parsing and batch uploading Excel file data, extending `BaseTemplate`, with support for status management and error data export.
+
+## [BaseTemplate](./BaseTemplate.md)
+
+## Overview
+
+The `BaseUploadTemplate` class extends `BaseTemplate`, adding batch upload functionality, progress status updates, and error data export capabilities. It supports parsing Excel files with custom column definitions, uploading data in batches, and providing status tracking and error handling features.
+
+## Usage
+
+To use `BaseUploadTemplate`, you must extend the class and implement the `uploadData` method to define the data upload logic. Below is an example:
+
+```typescript
+import BaseUploadTemplate from './BaseUploadTemplate';
+import type { DataColumn } from './DataColumn';
+
+class MyUploadTemplate extends BaseUploadTemplate {
+    constructor(columns: DataColumn[], batchSize: number = 50, rowOffset: number = 1) {
+        super(columns, batchSize, rowOffset);
+    }
+
+    protected async uploadData(list: Array<any>): Promise<Array<any>> {
+        // Implement data upload logic, e.g., calling an API
+        return list.map(item => ({ ...item, error: null }));
+    }
+}
+```
+
+### Parsing and Uploading Excel Files
+
+```typescript
+const file: File = // ... Obtain the file (e.g., from an input element)
+const columns: DataColumn[] = [
+    { field: 'name', text: 'Name', parser: (value) => String(value) },
+    { field: 'age', text: 'Age', parser: (value) => Number(value) }
+];
+const template = new MyUploadTemplate(columns);
+await template.parseExcelFile(file); // Parse the file
+await template.upload(); // Upload the data
+console.log(template.list); // Access processed data
+```
+
+### Exporting Error Data
+
+```typescript
+template.exportErrorRowsToExcel('errors.xlsx'); // Export data with errors to an Excel file
+```
+
+## Class Details
+
+### Constructor
+
+```typescript
+protected constructor(columns: Array<DataColumn>, batchSize: number = 50, rowOffset: number = 1)
+```
+
+- **Parameters**:
+  - `columns`: An array of `DataColumn` objects defining the data structure (field names, display text, and optional parsers).
+  - `batchSize`: The size of each upload batch (default: 50).
+  - `rowOffset`: The number of starting rows to skip in the Excel sheet (default: 1, e.g., to skip the header row).
+- **Description**: Initializes the template with column definitions, batch size, and row offset.
+
+### Methods
+
+#### `setProgressStatusListener`
+
+```typescript
+setProgressStatusListener(value: UpdateProgressStatus)
+```
+
+- **Parameters**:
+  - `value`: A callback function for updating progress status.
+- **Description**: Sets a listener to notify progress status updates, typically used for UI updates.
+
+#### `uploadData` (Abstract Method)
+
+```typescript
+protected abstract uploadData(list: Array<any>): Promise<Array<any>>
+```
+
+- **Parameters**:
+  - `list`: An array of data to upload.
+- **Description**: Subclasses must implement this method to define the data upload logic (e.g., calling a backend API). Returns an array containing the upload results, which may include error information.
+- **Override**: Subclasses must implement this method.
+
+#### `upload`
+
+```typescript
+async upload()
+```
+
+- **Description**: Uploads data in batches, updating the status of each record (`P` for pending, `U` for uploading, `D` for done), and invokes the progress status listener during the upload process.
+- **Logic**: Processes data in batches, calling `uploadData` for each batch and updating the error status of records based on the results.
+
+#### `wrapData`
+
+```typescript
+protected wrapData(data: any): any
+```
+
+- **Parameters**:
+  - `data`: A single row object.
+- **Description**: Wraps the data into an object containing `data` and `status` properties, with the initial status set to `P` (pending).
+- **Override**: Subclasses can override this method to customize the wrapping logic.
+
+#### `columns` (Getter)
+
+```typescript
+get columns(): Array<TableColumn>
+```
+
+- **Returns**: An array of `TableColumn` objects representing column definitions, including data columns and a status column.
+- **Description**: Extends `BaseTemplate`'s `columns`, adding a `data.` prefix to each field and appending a status column (displaying pending, uploading, success, or error information).
+
+#### `exportErrorRowsToExcel`
+
+```typescript
+exportErrorRowsToExcel(filename: string)
+```
+
+- **Parameters**:
+  - `filename`: The name of the exported Excel file.
+- **Description**: Filters rows with errors, generates an Excel file containing column headers, data values, and error information, and triggers a file download.
+- **Dependencies**: Uses the `xlsx` library to generate the Excel file.
+
+## Types
+
+- **DataColumn**: A custom type defining column metadata (e.g., `field`, `text`, `parser`, `visible`, `ignore`).
+- **TableColumn**: A type from `@ticatec/uniface-element/DataTable`, used for column definitions in UI components.
+- **UploadFun**: `(arr: Array<any>) => Promise<Array<any>>` type, representing the upload function.
+- **UpdateProgressStatus**: `() => void` type, representing the progress status update callback.
+
+## Status Column
+
+Defines an additional `statusColumn` to display the status of each row:
+
+```typescript
+const statusColumn: TableColumn = {
+    text: getI18nText(i18nKeys.labelStatus),
+    width: 240,
+    resizable: true,
+    formatter: row => {
+        if (row.status == 'P') {
+            return getI18nText(i18nKeys.status.pending)
+        } else if (row.status == 'U') {
+            return getI18nText(i18nKeys.status.uploading)
+        } else {
+            if (row.error) {
+                return row.errorText
+            } else {
+                return getI18nText(i18nKeys.status.successful)
+            }
+        }
+    }
+}
+```
+
+- **Status Values**:
+  - `P`: Pending
+  - `U`: Uploading
+  - `D`: Done (may include errors)
+- **Internationalization**: Uses `getI18nText` to retrieve status display text.
+
+## Notes
+
+- This class is abstract and must be extended with an implementation of the `uploadData` method.
+- Batch uploading is controlled by `batchSize` to avoid uploading too much data at once.
+- The error data export function includes only rows with errors, facilitating user analysis and correction.

package/documents/BaseUploadTemplate_cn.md

@@ -0,0 +1,172 @@
+
+# BaseUploadTemplate 类
+
+一个用于解析和批量上传 Excel 文件数据的抽象基类，继承自 `BaseTemplate`，支持状态管理和错误数据导出。
+
+## [BaseTemplate](./BaseTemplate_cn.md)
+
+## 概述
+
+`BaseUploadTemplate` 类扩展了 `BaseTemplate`，增加了批量上传功能、进度状态更新以及错误数据导出功能。它支持通过自定义列定义解析 Excel 文件，并以批次方式上传数据，同时提供状态跟踪和错误处理功能。
+
+## 使用方法
+
+要使用 `BaseUploadTemplate`，需继承该类并实现 `uploadData` 方法以定义数据上传逻辑。以下是一个示例：
+
+```typescript
+import BaseUploadTemplate from './BaseUploadTemplate';
+import type { DataColumn } from './DataColumn';
+
+class MyUploadTemplate extends BaseUploadTemplate {
+    constructor(columns: DataColumn[], batchSize: number = 50, rowOffset: number = 1) {
+        super(columns, batchSize, rowOffset);
+    }
+
+    protected async uploadData(list: Array<any>): Promise<Array<any>> {
+        // 实现数据上传逻辑，例如调用 API
+        return list.map(item => ({ ...item, error: null }));
+    }
+}
+```
+
+### 解析和上传 Excel 文件
+
+```typescript
+const file: File = // ... 获取文件（例如，从输入元素获取）
+const columns: DataColumn[] = [
+    { field: 'name', text: '姓名', parser: (value) => String(value) },
+    { field: 'age', text: '年龄', parser: (value) => Number(value) }
+];
+const template = new MyUploadTemplate(columns);
+await template.parseExcelFile(file); // 解析文件
+await template.upload(); // 上传数据
+console.log(template.list); // 访问处理后的数据
+```
+
+### 导出错误数据
+
+```typescript
+template.exportErrorRowsToExcel('errors.xlsx'); // 导出包含错误的数据到 Excel 文件
+```
+
+## 类详情
+
+### 构造函数
+
+```typescript
+protected constructor(columns: Array<DataColumn>, batchSize: number = 50, rowOffset: number = 1)
+```
+
+- **参数**：
+    - `columns`：定义数据结构（字段名、显示文本和可选解析器）的 `DataColumn` 对象数组。
+    - `batchSize`：每次上传的批次大小（默认：50）。
+    - `rowOffset`：Excel 表中要跳过的起始行数（默认：1，例如跳过标题行）。
+- **描述**：初始化模板，设置列定义、批次大小和行偏移。
+
+### 方法
+
+#### `setProgressStatusListener`
+
+```typescript
+setProgressStatusListener(value: UpdateProgressStatus)
+```
+
+- **参数**：
+    - `value`：进度状态更新回调函数。
+- **描述**：设置用于通知进度状态更新的监听器，通常用于 UI 更新。
+
+#### `uploadData` (抽象方法)
+
+```typescript
+protected abstract uploadData(list: Array<any>): Promise<Array<any>>
+```
+
+- **参数**：
+    - `list`：要上传的数据数组。
+- **描述**：子类必须实现此方法以定义数据上传逻辑（例如，调用后端 API）。返回包含上传结果的数组，可能包含错误信息。
+- **重写**：子类需实现此方法。
+
+#### `upload`
+
+```typescript
+async upload()
+```
+
+- **描述**：按批次上传数据，更新每条记录的状态（`P` 表示待处理，`U` 表示上传中，`D` 表示完成），并在上传过程中调用进度状态监听器。
+- **逻辑**：将数据分批处理，每批调用 `uploadData`，并根据结果更新记录的错误状态。
+
+#### `wrapData`
+
+```typescript
+protected wrapData(data: any): any
+```
+
+- **参数**：
+    - `data`：单个行对象。
+- **描述**：将数据包装为包含 `data` 和 `status` 属性的对象，初始状态为 `P`（待处理）。
+- **重写**：子类可重写此方法以自定义包装逻辑。
+
+#### `columns`（获取器）
+
+```typescript
+get columns(): Array<TableColumn>
+```
+
+- **返回**：`TableColumn` 对象的数组，表示列定义，包含数据列和状态列。
+- **描述**：扩展 `BaseTemplate` 的 `columns`，为每个字段添加 `data.` 前缀，并附加一个状态列（显示待处理、上传中、成功或错误信息）。
+
+#### `exportErrorRowsToExcel`
+
+```typescript
+exportErrorRowsToExcel(filename: string)
+```
+
+- **参数**：
+    - `filename`：导出的 Excel 文件名。
+- **描述**：筛选包含错误的行，生成 Excel 文件，包含列标题、数据值和错误信息，并触发文件下载。
+- **依赖**：使用 `xlsx` 库生成 Excel 文件。
+
+## 类型
+
+- **DataColumn**：自定义类型，定义列元数据（例如 `field`、`text`、`parser`、`visible`、`ignore`）。
+- **TableColumn**：来自 `@ticatec/uniface-element/DataTable` 的类型，用于 UI 组件中的列定义。
+- **UploadFun**：`(arr: Array<any>) => Promise<Array<any>>` 类型，表示上传函数。
+- **UpdateProgressStatus**：`() => void` 类型，表示进度状态更新回调。
+
+## 状态列
+
+定义了一个额外的 `statusColumn` 用于显示每行数据的状态：
+
+```typescript
+const statusColumn: TableColumn = {
+    text: getI18nText(i18nKeys.labelStatus),
+    width: 240,
+    resizable: true,
+    formatter: row => {
+        if (row.status == 'P') {
+            return getI18nText(i18nKeys.status.pending)
+        } else if (row.status == 'U') {
+            return getI18nText(i18nKeys.status.uploading)
+        } else {
+            if (row.error) {
+                return row.errorText
+            } else {
+                return getI18nText(i18nKeys.status.successful)
+            }
+        }
+    }
+}
+```
+
+- **状态值**：
+    - `P`：待处理（Pending）
+    - `U`：上传中（Uploading）
+    - `D`：完成（Done，可能包含错误）
+- **国际化**：使用 `getI18nText` 获取状态显示文本。
+
+
+## 注意事项
+
+- 该类为抽象类，必须继承并实现 `uploadData` 方法。
+- 批量上传通过 `batchSize` 控制，避免一次性上传过多数据。
+- 错误数据导出功能仅包含有错误的行，便于用户分析和修复。

package/documents/EncodingWizard.md

@@ -0,0 +1,89 @@
+# Excel Encoding Wizard Component
+
+A Svelte-based dialog component for parsing Excel files, validating/completing data via a server-side API, and displaying validation results, integrated with `BaseEncodingTemplate` for data processing.
+
+## Overview
+
+This component provides an interactive dialog interface that allows users to select an Excel file, parse its contents, validate and complete data through a server-side API, display a data table, and provide a confirm action when the data is valid. The component supports internationalization and dynamic button operations, making it suitable for scenarios requiring validation and completion of Excel data.
+
+## Usage
+
+Embed the component in a Svelte application and pass the required properties. Below is an example:
+
+1. Implement a data template to define fields matching the Excel file. [BaseEncodingTemplate](./BaseEncodingTemplate.md)
+2. Open the dialog to load a local Excel file, which triggers parsing and validation via the server API. If validation passes, a confirm button is displayed. Clicking the confirm button returns the dataset through a callback function.
+
+```typescript
+<script lang="ts">
+    import EncodingDialog from '@ticatec/batch-data-uploader/EncodingDialog.svelte';
+    import type { DataColumn } from '@ticatec/batch-data-uploader/DataColumn';
+    import MyEncodingTemplate from './MyEncodingTemplate'; // Extends BaseEncodingTemplate
+
+    const template = new MyEncodingTemplate();
+
+    function handleClose() {
+        console.log('Dialog closed');
+    }
+
+    function handleConfirm(data: any[]) {
+        console.log('Confirmed data:', data);
+    }
+</script>
+
+<ExcelEncodingDialog
+    title="Validate Excel Data"
+    width="800px"
+    height="600px"
+    {template}
+    closeHandler={handleClose}
+    confirmCallback={handleConfirm}
+/>
+```
+
+## Component Details
+
+### Properties
+
+- **title**: `string`
+  - The dialog title.
+- **width**: `string` (default: `"800px"`)
+  - The dialog width.
+- **height**: `string` (default: `"600px"`)
+  - The dialog height.
+- **template**: `BaseEncodingTemplate`
+  - An instance of `BaseEncodingTemplate` used for parsing Excel files, validating, and completing data.
+- **confirmCallback**: `any`
+  - A callback function invoked when the confirm button is clicked, receiving the parsed data list (`template.list`).
+
+### Button Actions
+
+- **btnChoose**: File selection button that triggers a file input dialog to choose an Excel file.
+- **btnConfirm**: Confirm button, displayed only when the data is valid (`template.valid` is `true`), invokes `confirmCallback,` and closes the dialog.
+
+### Event Handling
+
+- **File Selection**: Triggered via a hidden `<input type="file">` element, which calls `parseExcelFile` to parse the selected Excel file and invokes `template.parseExcelFile` for validation/completion.
+- **Data Validation**: After parsing, checks `template.valid`. If the data is valid, adds the "Confirm" button.
+- **Error Prompt**: Displays an error message via `window.Toast` if parsing fails and hides the loading indicator.
+
+## Types
+
+- **DataColumn**: A custom interface defining column metadata (extends `TableColumn` from `@ticatec/uniface-element/DataTable`).
+- **ButtonAction** / **ButtonActions**: From `@ticatec/uniface-element/ActionBar`, defining button operations.
+- **IndicatorColumn**: From `@ticatec/uniface-element/DataTable`, defining the row number column.
+
+## Dependent Components
+
+- **Dialog**: From `@ticatec/uniface-element/Dialog`, provides the dialog container.
+- **DataTable**: From `@ticatec/uniface-element/DataTable`, displays the data table.
+- **Box**: From `@ticatec/uniface-element/Box`, provides a bordered container style.
+- **getI18nText**: From `@ticatec/i18n`, used for internationalized text.
+
+## Notes
+
+- Ensure `BaseEncodingTemplate` correctly implements `isDataValid`, `encodeData`, and the `valid` property to support data validation and completion.
+- The file input only accepts `.xls` and `.xlsx` file formats.
+- A loading indicator (`window.Indicator`) is displayed during parsing, and errors are shown via `window.Toast`.
+- The confirm button is displayed only when `template.valid` is `true`, ensuring only valid data can be submitted.
+- The component depends on `window.Indicator` and `window.Toast` for UI prompts; ensure these global objects are defined.
+- The `confirmCallback` receives the complete parsed data list, suitable for further processing or submission.