@xeplr/ui-utils 1.0.9 → 1.0.10

package/README.md

@@ -118,7 +118,7 @@ export default function SelectCompany() {
 | `useNumberFieldController(props)` | NumberFieldPage props | `type, raw, numeric, error, placeholder, disabled, decimals, formatDisplay, affix {list, selected, position, labelKey, valueKey} \| null, handleNumberChange, handleAffixChange, handleBlur` |
 | `useTextFieldController(props)` | TextFieldPage props | `type, raw, error, remaining, placeholder, disabled, required, maxLength, rows, label, help, handleChange, handleBlur, handleKeyDown, handleClear` |
 | `useFileUploadController(options)` | FileUploadPage props | `files, uploading, progress, error, result, dragOver, inputRef, handleChange, handleDragOver, handleDragLeave, handleDrop, handleUpload, openFilePicker, removeFile(i), clear, allowedTypes, maxSize, maxFiles` |
-| `useDataImportController(options)` | DataImportPage props | `file, inspecting, inspected, mappings, committing, results, error, handleFileChange, updateMapping(i, patch), handleCommit, reset, accept, targetLabel` |
+| `useDataImportController(options)` | DataImportPage props | `file, inspecting, inspected, mappings, committing, results, error, handleFileChange, updateMapping(i, patch), setFix(i, key, on), checksOf(part), handleCommit, reset, accept, targetLabel` |
 | `useImportHistoryController(options)` | ImportHistoryPage props | `jobs, loading, error, rollingBackId, deletingId, reload, handleRollback(job), handleDelete(job)` |
 | `useGridDisplayerController(props)` | GridDisplayerPage props | `query, setQuery, sortFields, sortValue, setSortValue, displayRows, tileFormatComponent, onSelect, onAddNew` |
 | `useColorPickerController(props)` | ColorPickerPage props | `label, value, hex, opacity, swatches [{color, selected}], custom, allowNone, allowOpacity, previewText, pick(hex), setOpacity(0–100), clear` |
@@ -146,7 +146,7 @@ export default function SelectCompany() {
 | `toggleOpen`, `initialOpen` | `(open, key, multiple?) → keys`, `(items, initial?, multiple?) → keys` | Which expanders are open |
 | `toggleBranch`, `decorateTree` | `(open, parentKey, key) → open`, `(nodes, open) → nodes` | Which branch of a settings tree is open at each level; `open` is `{ [parentKey]: key }`, the root's parent `''` |
 | `filterGridRows`, `sortGridRows` | `(rows, query, fields)`, `(rows, field, 'asc'\|'desc')` | Grid search and sort. An array field matches if any entry matches. |
-| `sanitizeTargetName`, `buildInitialMappings` | `(name) → string`, `({ parts?, originalName? }) → [{ part, target, include }]` | Data import mapping |
+| `sanitizeTargetName`, `buildInitialMappings`, `checksFor` | `(name) → string`, `({ parts?, originalName?, checks? }) → [{ part, target, include, fixes }]`, `(inspectResult, part) → checks[]` | Data import mapping |
 | `configureUpload`, `uploadFile` | `({ url, headers, getHeaders })`, `(files, { url, fieldName, extraData, onProgress }) → Promise` | Multipart upload over XHR |
 | `attachProgressSource`, `progressSourceAttached`, `subscribeToProgress`, `describeProgress`, `describeComplete` | `(subscribe)`, `() → boolean`, `(key, handler) → unsubscribe`, `(data, noun?)`, `(data, noun?)` | The progress event source and its sentences |
 
@@ -294,13 +294,15 @@ configureUpload({ url: '/uploads', getHeaders: () => ({ Authorization: 'Bearer '
 
 | prop | type | meaning |
 |---|---|---|
-| `onInspect` | `(filePath, file) => Promise<{ format, parts? }>` | **Required.** Say what an uploaded file contains. `parts` holds, for example, an Excel workbook's sheet names. |
-| `onCommit` | `(filePath, [{ part, target }], { originalName }) => Promise<{ results } \| results[]>` | **Required.** Load the included parts into their targets. |
+| `onInspect` | `(filePath, file) => Promise<{ format, parts?, checks? }>` | **Required.** Say what an uploaded file contains. `parts` holds, for example, an Excel workbook's sheet names. `checks` says what is wrong with a part before it is loaded — see below. |
+| `onCommit` | `(filePath, [{ part, target, fixes }], { originalName }) => Promise<{ results } \| results[]>` | **Required.** Load the included parts into their targets. `fixes` is the person's choice for each fix the checks offered. |
 | `accept` | `string` | The file input's `accept` attribute, for example `'.csv,.json,.xlsx,.xls'` |
 | `targetLabel` | `string` | Placeholder for the target name (default `'Target'`) |
 
 The file is sent through this package's own `uploadFile()` to the URL set by `configureUpload`, not through a prop. That keeps the component free of app-specific upload wiring. The apps point it at `@xeplr/base-apis`' generic upload route. The upload response must include `filePath`. With `parts`, each part becomes a row (included by default) whose target is `sanitizeTargetName(part)`. Without `parts`, there is one row named after the file. Result rows show `target (part)` and then `rows` + " rows", "Done", or `error`, depending on `success`.
 
+**Checks, before anything is loaded.** `onInspect` may return `checks: { [part]: [{ key, message, fixLabel?, fixDefault?, examples? }] }` (the key `''` for a one-unit file). Each shows under its part as a warning with its message and examples. One with a `fixLabel` offers the fix as a checkbox, on unless `fixDefault: false`; the choice reaches `onCommit` as `fixes[key]`. A result row's `note` is shown under it — what a fix did. The component knows no particular check: the app decides what to look for and what its fix means (BI: rows pasted into one cell, recovered).
+
 `sanitizeTargetName('Sales 2024.xlsx')` returns `'sales_2024'`. It lowercases, drops the extension, turns runs of non-`[a-z0-9_]` characters into `_`, trims `_` from both ends, and falls back to `'table'`.
 
 ## ImportHistoryPage

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/ui-utils",
-  "version": "1.0.9",
+  "version": "1.0.10",
   "description": "UI utility components: file upload with progress, snackbar, static data (countries/states)",
   "type": "module",
   "main": "src/index.js",

package/src/dataImport/dataImport.js

@@ -16,8 +16,26 @@ export function sanitizeTargetName(name) {
     .replace(/^_+|_+$/g, '') || 'table';
 }
 
-// inspectResult: { filePath, format, originalName?, parts?: string[] }
-// -> [{ part: string|null, target: string, include: boolean }]
+// What the inspect step found wrong with one part, if anything:
+//   inspectResult.checks = { [part]: [{ key, message, fixLabel?, fixDefault? }] }
+// (the key '' for a file that is one unit). A check with a fixLabel offers a
+// fix the person switches on or off before importing; its choice travels
+// with the mapping as fixes[key].
+export function checksFor(inspectResult, part) {
+  var all = (inspectResult && inspectResult.checks) || {};
+  return all[part == null ? '' : part] || [];
+}
+
+function initialFixes(inspectResult, part) {
+  var fixes = {};
+  checksFor(inspectResult, part).forEach(function(c) {
+    if (c.fixLabel) fixes[c.key] = c.fixDefault !== false;
+  });
+  return fixes;
+}
+
+// inspectResult: { filePath, format, originalName?, parts?: string[], checks? }
+// -> [{ part: string|null, target: string, include: boolean, fixes: { [key]: boolean } }]
 //
 // parts present (e.g. Excel sheets) -> one row per part, all included by
 // default. parts absent (e.g. CSV/JSON — the whole file is one unit) -> a
@@ -25,8 +43,8 @@ export function sanitizeTargetName(name) {
 export function buildInitialMappings(inspectResult) {
   if (inspectResult.parts && inspectResult.parts.length) {
     return inspectResult.parts.map(function(part) {
-      return { part: part, target: sanitizeTargetName(part), include: true };
+      return { part: part, target: sanitizeTargetName(part), include: true, fixes: initialFixes(inspectResult, part) };
     });
   }
-  return [{ part: null, target: sanitizeTargetName(inspectResult.originalName || 'data'), include: true }];
+  return [{ part: null, target: sanitizeTargetName(inspectResult.originalName || 'data'), include: true, fixes: initialFixes(inspectResult, null) }];
 }

package/src/dataImport/designs/DataImportSample.jsx

@@ -2,7 +2,7 @@ import './dataImport.css';
 
 export default function DataImportSample({
   file, inspecting, inspected, mappings, committing, results, error,
-  handleFileChange, updateMapping, handleCommit, reset, accept, targetLabel
+  handleFileChange, updateMapping, setFix, checksOf, handleCommit, reset, accept, targetLabel
 }) {
   return (
     <div className="xeplr-data-import">
@@ -37,6 +37,31 @@ export default function DataImportSample({
                   onChange={function(e) { updateMapping(i, { target: e.target.value }); }}
                   placeholder={targetLabel}
                 />
+                {/* What the inspect step found, before anything is loaded —
+                    and the fix, when one is offered, as a choice. */}
+                {(checksOf ? checksOf(m.part) : []).map(function(c) {
+                  return (
+                    <div key={c.key} className="xeplr-data-import-check" role="alert">
+                      <p className="xeplr-data-import-check-message">{c.message}</p>
+                      {c.fixLabel && (
+                        <label className="xeplr-data-import-check-fix">
+                          <input
+                            type="checkbox"
+                            checked={Boolean(m.fixes && m.fixes[c.key])}
+                            disabled={!m.include}
+                            onChange={function(e) { setFix(i, c.key, e.target.checked); }}
+                          />
+                          {c.fixLabel}
+                        </label>
+                      )}
+                      {(c.examples || []).length > 0 && (
+                        <ul className="xeplr-data-import-check-examples">
+                          {c.examples.map(function(x, xi) { return <li key={xi}>{x}</li>; })}
+                        </ul>
+                      )}
+                    </div>
+                  );
+                })}
               </div>
             );
           })}
@@ -61,6 +86,7 @@ export default function DataImportSample({
                 <span className={r.success ? 'xeplr-data-import-result-ok' : 'xeplr-data-import-result-fail'}>
                   {r.success ? (r.rows != null ? r.rows + ' rows' : 'Done') : (r.error || 'Failed')}
                 </span>
+                {r.note && <span className="xeplr-data-import-result-note">{r.note}</span>}
               </div>
             );
           })}

package/src/dataImport/designs/dataImport.css

@@ -96,3 +96,22 @@
 .xeplr-import-history-status-failed { color: var(--xeplr-danger, #ff6b6b); }
 .xeplr-import-history-status-rolled-back { color: var(--xeplr-text-muted, #888); }
 .xeplr-import-history-error { color: var(--xeplr-text-secondary, #999); }
+
+/* What the inspect step found in a part — on its own line under the part,
+   with the fix (when one is offered) as a checkbox the person decides. */
+.xeplr-data-import-mapping-row { flex-wrap: wrap; }
+.xeplr-data-import-check {
+  flex-basis: 100%;
+  margin: 2px 0 4px;
+  padding: 10px 12px;
+  border-radius: 8px;
+  border: 1px solid var(--xeplr-warning, #a86a00);
+  background: var(--xeplr-warning-bg, rgba(168, 106, 0, 0.08));
+  color: var(--xeplr-text-primary, #e0e0e0);
+  font-size: 13px;
+}
+.xeplr-data-import-check-message { margin: 0 0 6px; line-height: 1.45; }
+.xeplr-data-import-check-fix { display: flex; align-items: center; gap: 8px; font-weight: 600; cursor: pointer; }
+.xeplr-data-import-check-examples { margin: 6px 0 0; padding-left: 18px; font-size: 12px; color: var(--xeplr-text-muted, #888); }
+.xeplr-data-import-result-note { flex-basis: 100%; font-size: 12px; color: var(--xeplr-text-muted, #888); }
+.xeplr-data-import-result-row { flex-wrap: wrap; }

package/src/dataImport/useDataImportController.js

@@ -1,16 +1,18 @@
 import { useState } from 'react';
 import { uploadFile } from '../fileUpload/uploadFile.js';
-import { buildInitialMappings } from './dataImport.js';
+import { buildInitialMappings, checksFor } from './dataImport.js';
 
 /**
  * @param {object} options
  * @param {string} [options.accept] - file input accept attribute, e.g. '.csv,.json,.xlsx,.xls'
  * @param {string} [options.targetLabel='Target'] - placeholder/label for the target-name field
- * @param {(filePath: string, file: File) => Promise<{format: string, parts?: string[]}>} options.onInspect
+ * @param {(filePath: string, file: File) => Promise<{format: string, parts?: string[], checks?: object}>} options.onInspect
  *   - required. App-supplied: given a file ALREADY uploaded (see below), what
  *     does it contain? (format, and for a multi-part file like an Excel
  *     workbook, its part/sheet names).
- * @param {(filePath: string, mappings: {part: string|null, target: string}[], meta: {originalName: string}) => Promise<{results: object[]}>} options.onCommit
+ * @param {(filePath: string, mappings: {part: string|null, target: string, fixes: object}[], meta: {originalName: string}) => Promise<{results: object[]}>} options.onCommit
+ *   (each mapping's `fixes` is the person's choice for each fix the inspect
+ *   step's `checks` offered — see checksFor in dataImport.js)
  *   - required. App-supplied: load the included parts into their targets.
  *     meta.originalName is the picked file's own name (not the server-side
  *     path) — pass it through if the app wants it recorded (e.g. import
@@ -61,6 +63,15 @@ export function useDataImportController(options = {}) {
     }
   }
 
+  // A fix the inspect step offered, switched on or off for one part.
+  function setFix(index, key, on) {
+    setMappings(function(prev) {
+      var next = prev.slice();
+      next[index] = Object.assign({}, next[index], { fixes: Object.assign({}, next[index].fixes, { [key]: on }) });
+      return next;
+    });
+  }
+
   function updateMapping(index, patch) {
     setMappings(function(prev) {
       var next = prev.slice();
@@ -75,7 +86,7 @@ export function useDataImportController(options = {}) {
     setCommitting(true);
     setError('');
     try {
-      var payload = included.map(function(m) { return { part: m.part, target: m.target }; });
+      var payload = included.map(function(m) { return { part: m.part, target: m.target, fixes: m.fixes || {} }; });
       var res = await options.onCommit(inspected.filePath, payload, { originalName: inspected.originalName });
       setResults((res && res.results) || res || []);
     } catch (err) {
@@ -87,7 +98,8 @@ export function useDataImportController(options = {}) {
 
   return {
     file, inspecting, inspected, mappings, committing, results, error,
-    handleFileChange, updateMapping, handleCommit, reset,
+    handleFileChange, updateMapping, setFix, handleCommit, reset,
+    checksOf: function(part) { return checksFor(inspected, part); },
     accept: options.accept,
     targetLabel: options.targetLabel || 'Target'
   };