@xeplr/ui-utils 1.0.0 → 1.0.2

package/package.json

@@ -1,16 +1,35 @@
 {
   "name": "@xeplr/ui-utils",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "UI utility components: file upload with progress, snackbar, static data (countries/states)",
   "type": "module",
   "main": "src/index.js",
-  "files": ["src/"],
-  "keywords": ["react", "hooks", "file-upload", "ui", "utilities", "countries", "states"],
+  "files": [
+    "src/"
+  ],
+  "keywords": [
+    "react",
+    "hooks",
+    "file-upload",
+    "ui",
+    "utilities",
+    "countries",
+    "states"
+  ],
   "author": "xeplr",
   "license": "MIT",
-  "repository": { "type": "git", "url": "https://github.com/Xeplr/xeplr-ui-utils" },
-  "publishConfig": { "access": "public" },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Xeplr/xeplr-ui-utils"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "peerDependencies": {
-    "react": "^18.0.0 || ^19.0.0"
+    "react": "^18.0.0 || ^19.0.0",
+    "@xeplr/ui-table": "^1.0.0"
+  },
+  "scripts": {
+    "test": "for f in test/*.test.js; do node \"$f\" || exit 1; done"
   }
 }

package/src/confirm/confirm.js

@@ -0,0 +1,175 @@
+// Imperative, self-mounting modal dialogs — same shape as ../snackbar/snackbar.js
+// (own DOM node, inline styles, no provider/mount point needed, no CSS import).
+// Unlike the snackbar these are modal and return a Promise, since a caller needs
+// the answer before proceeding (e.g. "enter this workspace?").
+//
+// Two shapes, ONE dialog surface:
+//   raiseConfirm — yes/no. The common case, and unchanged.
+//   raiseChoice  — any number of answers, because some questions genuinely have
+//                  three. "You have unsaved changes and you are leaving" is the
+//                  standing example: save, discard, or come back — and folding
+//                  that into a boolean forces the caller to either drop one of
+//                  the three or ask twice.
+//
+// They share _root and _cancelPending deliberately: two dialog surfaces could
+// each hold one open at once, and the second would silently cover the first.
+
+var _root = null;
+// A second dialog before the first resolves would otherwise stack a second
+// overlay into the same _root and add a second document keydown listener —
+// cancel whatever's still open before mounting a new one.
+var _cancelPending = null;
+
+function ensureRoot() {
+  if (_root) return _root;
+  _root = document.createElement('div');
+  _root.id = 'xeplr-confirm-root';
+  document.body.appendChild(_root);
+  return _root;
+}
+
+/**
+ * The shell both shapes are built from.
+ *
+ * @param {object} spec
+ * @param {string}   spec.title
+ * @param {string}   spec.message
+ * @param {Array}    spec.buttons   - [{ label, value, style: 'primary'|'danger'|'plain', isDefault }]
+ *                                    rendered left to right; the LAST one is focused.
+ * @param {*}        spec.dismissValue - what Escape, the overlay and a superseding
+ *                                    dialog all resolve to.
+ * @returns {Promise<*>} the chosen button's `value`
+ */
+function openDialog(spec) {
+  if (_cancelPending) _cancelPending();
+
+  return new Promise(function(resolve) {
+    var root = ensureRoot();
+
+    function cleanup(result) {
+      document.removeEventListener('keydown', onKeyDown);
+      root.innerHTML = '';
+      if (_cancelPending === cleanupAsDismiss) _cancelPending = null;
+      resolve(result);
+    }
+
+    function cleanupAsDismiss() { cleanup(spec.dismissValue); }
+    _cancelPending = cleanupAsDismiss;
+
+    function onKeyDown(e) {
+      if (e.key === 'Escape') cleanup(spec.dismissValue);
+      if (e.key === 'Enter') {
+        // Enter takes the DEFAULT, and only if one was named. With three
+        // answers there is no obvious one to guess at, and guessing would
+        // commit somebody's work — or throw it away — on a stray keypress.
+        for (var i = 0; i < spec.buttons.length; i++) {
+          if (spec.buttons[i].isDefault) return cleanup(spec.buttons[i].value);
+        }
+      }
+    }
+
+    // var(--xeplr-*, fallback) — picks up @xeplr/ui-account's theme tokens
+    // (light/dark, whichever .xeplr-theme-* an ancestor applies) when that
+    // stylesheet is loaded, falls back to the original dark palette otherwise.
+    var overlay = document.createElement('div');
+    overlay.style.cssText = 'position:fixed;inset:0;background:var(--xeplr-bg-overlay,rgba(0,0,0,0.55));z-index:100000;'
+      + 'display:flex;align-items:center;justify-content:center;';
+    overlay.onclick = function(e) { if (e.target === overlay) cleanup(spec.dismissValue); };
+
+    var box = document.createElement('div');
+    box.style.cssText = 'background:var(--xeplr-bg-tertiary,#1a1a1a);color:var(--xeplr-text-primary,#e0e0e0);'
+      + 'border:1px solid var(--xeplr-border-primary,#333);border-radius:10px;'
+      + 'padding:20px;max-width:420px;width:calc(100% - 40px);font:14px/1.5 system-ui,sans-serif;'
+      + 'box-shadow:var(--xeplr-shadow-lg,0 12px 32px rgba(0,0,0,0.4));';
+
+    var titleEl = document.createElement('div');
+    titleEl.style.cssText = 'font-size:16px;font-weight:600;margin-bottom:8px;';
+    titleEl.textContent = spec.title;
+
+    var messageEl = document.createElement('div');
+    messageEl.style.cssText = 'color:var(--xeplr-text-secondary,#bbb);margin-bottom:18px;';
+    messageEl.textContent = spec.message;
+
+    var actions = document.createElement('div');
+    // Wraps, because three labels that each say what they DO ("Leave without
+    // saving") are longer than "OK" and must not run off a narrow dialog.
+    actions.style.cssText = 'display:flex;justify-content:flex-end;gap:8px;flex-wrap:wrap;';
+
+    var lastBtn = null;
+    spec.buttons.forEach(function(def) {
+      var btn = document.createElement('button');
+      btn.type = 'button';
+      btn.textContent = def.label;
+      if (def.style === 'primary' || def.style === 'danger') {
+        var bg = def.style === 'danger' ? 'var(--xeplr-danger,#dc2626)' : 'var(--xeplr-accent,#646cff)';
+        btn.style.cssText = 'padding:8px 14px;border:none;border-radius:6px;'
+          + 'background:' + bg + ';color:var(--xeplr-accent-text,#fff);font-size:13px;font-weight:600;cursor:pointer;';
+      } else {
+        btn.style.cssText = 'padding:8px 14px;border:1px solid var(--xeplr-border-primary,#444);border-radius:6px;'
+          + 'background:var(--xeplr-bg-secondary,#232323);color:var(--xeplr-text-primary,#e0e0e0);font-size:13px;cursor:pointer;';
+      }
+      btn.onclick = function() { cleanup(def.value); };
+      actions.appendChild(btn);
+      lastBtn = btn;
+    });
+
+    box.appendChild(titleEl);
+    box.appendChild(messageEl);
+    box.appendChild(actions);
+    overlay.appendChild(box);
+    root.appendChild(overlay);
+
+    document.addEventListener('keydown', onKeyDown);
+    if (lastBtn) lastBtn.focus();
+  });
+}
+
+/**
+ * @param {string} message
+ * @param {object} [options]
+ * @param {string} [options.title='Are you sure?']
+ * @param {string} [options.confirmLabel='Confirm']
+ * @param {string} [options.cancelLabel='Cancel']
+ * @param {boolean} [options.danger=false] - style the confirm button as destructive
+ * @returns {Promise<boolean>} resolves true (confirmed) or false (cancelled/dismissed)
+ */
+export function raiseConfirm(message, options) {
+  options = options || {};
+  return openDialog({
+    title: options.title || 'Are you sure?',
+    message: message,
+    dismissValue: false,
+    buttons: [
+      { label: options.cancelLabel || 'Cancel', value: false, style: 'plain' },
+      { label: options.confirmLabel || 'Confirm', value: true, isDefault: true,
+        style: options.danger ? 'danger' : 'primary' }
+    ]
+  });
+}
+
+/**
+ * A question with more than two answers.
+ *
+ * @param {string} message
+ * @param {object} options
+ * @param {string}  [options.title='Are you sure?']
+ * @param {Array}   options.choices - [{ value, label, style?, isDefault? }], left to
+ *                  right; the last is focused, and `style` is 'primary' | 'danger' |
+ *                  omitted for plain. Put the answer somebody most likely wants last.
+ * @param {*}       [options.dismissValue=null] - Escape / clicking away / being
+ *                  superseded. Default null, so "they closed the dialog" is
+ *                  distinguishable from every deliberate answer.
+ * @returns {Promise<*>} the chosen `value`
+ */
+export function raiseChoice(message, options) {
+  options = options || {};
+  var choices = options.choices || [];
+  return openDialog({
+    title: options.title || 'Are you sure?',
+    message: message,
+    dismissValue: options.dismissValue === undefined ? null : options.dismissValue,
+    buttons: choices.map(function(c) {
+      return { label: c.label, value: c.value, style: c.style || 'plain', isDefault: c.isDefault };
+    })
+  });
+}

package/src/dataImport/dataImport.js

@@ -0,0 +1,32 @@
+// DataImport — model. Pure functions, no React/DOM — see
+// useDataImportController.js for the stateful wiring.
+//
+// The shape this whole module works with: a file is inspected (app-supplied
+// onInspect) and comes back as either a single unit or a list of named
+// PARTS (e.g. an Excel workbook's sheet names) — each part maps to a named
+// TARGET the app will load it into (e.g. a DB table). Deliberately generic
+// vocabulary (part/target, not sheet/table) — the app decides what a "part"
+// and "target" mean; this module only handles the mapping UI + flow.
+
+export function sanitizeTargetName(name) {
+  return String(name || '')
+    .toLowerCase()
+    .replace(/\.[^/.]+$/, '')        // strip a file extension, if any
+    .replace(/[^a-z0-9_]+/g, '_')
+    .replace(/^_+|_+$/g, '') || 'table';
+}
+
+// inspectResult: { filePath, format, originalName?, parts?: string[] }
+// -> [{ part: string|null, target: string, include: 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
+// single row with part:null, named from the file itself.
+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: null, target: sanitizeTargetName(inspectResult.originalName || 'data'), include: true }];
+}

package/src/dataImport/designs/DataImportSample.jsx

@@ -0,0 +1,71 @@
+import './dataImport.css';
+
+export default function DataImportSample({
+  file, inspecting, inspected, mappings, committing, results, error,
+  handleFileChange, updateMapping, handleCommit, reset, accept, targetLabel
+}) {
+  return (
+    <div className="xeplr-data-import">
+      <label className="xeplr-data-import-dropzone">
+        <input type="file" accept={accept} onChange={handleFileChange} />
+        {file ? file.name : 'Choose a file to import'}
+      </label>
+
+      {inspecting && <p className="xeplr-data-import-hint">Inspecting file…</p>}
+      {error && <div className="xeplr-data-import-alert xeplr-data-import-alert-error">{error}</div>}
+
+      {inspected && mappings.length > 0 && (
+        <div className="xeplr-data-import-mappings">
+          {mappings.map(function(m, i) {
+            return (
+              <div key={m.part || 'single'} className="xeplr-data-import-mapping-row">
+                {m.part && (
+                  <label className="xeplr-data-import-mapping-check">
+                    <input
+                      type="checkbox"
+                      checked={m.include}
+                      onChange={function(e) { updateMapping(i, { include: e.target.checked }); }}
+                    />
+                    {m.part}
+                  </label>
+                )}
+                <span className="xeplr-data-import-mapping-arrow">&rarr;</span>
+                <input
+                  type="text"
+                  value={m.target}
+                  disabled={!m.include}
+                  onChange={function(e) { updateMapping(i, { target: e.target.value }); }}
+                  placeholder={targetLabel}
+                />
+              </div>
+            );
+          })}
+        </div>
+      )}
+
+      {inspected && mappings.length > 0 && (
+        <div className="xeplr-data-import-actions">
+          <button type="button" onClick={handleCommit} disabled={committing || !mappings.some(function(m) { return m.include; })}>
+            {committing ? 'Importing…' : 'Import'}
+          </button>
+          <button type="button" onClick={reset} disabled={committing}>Cancel</button>
+        </div>
+      )}
+
+      {results && results.length > 0 && (
+        <div className="xeplr-data-import-results">
+          {results.map(function(r, i) {
+            return (
+              <div key={i} className="xeplr-data-import-result-row">
+                <span>{r.target}{r.part ? ' (' + r.part + ')' : ''}</span>
+                <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>
+              </div>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/dataImport/designs/ImportHistorySample.jsx

@@ -0,0 +1,130 @@
+import './dataImport.css';
+import { XeplrTable } from '@xeplr/ui-table';
+import { raiseConfirm } from '../../confirm/confirm.js';
+
+var STATUS_LABEL = {
+  completed: 'Completed',
+  failed: 'Failed',
+  'rolled-back': 'Rolled back'
+};
+
+function formatWhen(value) {
+  if (!value) return '';
+  var d = new Date(value);
+  if (isNaN(d.getTime())) return String(value);
+  return d.toLocaleString();
+}
+
+var SCHEMA = {
+  0: {
+    columns: [
+      {
+        accessor: 'originalFileName',
+        header: 'File',
+        cell: function(info) {
+          var job = info.row.original;
+          return job.originalFileName + (job.part ? ' (' + job.part + ')' : '');
+        }
+      },
+      {
+        accessor: 'destination',
+        header: 'Destination',
+        cell: function(info) { return info.getValue() || '—'; }
+      },
+      { accessor: 'target', header: 'Target' },
+      {
+        accessor: 'rows',
+        header: 'Rows',
+        cell: function(info) {
+          var job = info.row.original;
+          var total = info.getValue();
+          if (total == null) return '—';
+          if (job.rowsLoaded != null || job.rowsDropped != null) {
+            var loaded = job.rowsLoaded != null ? job.rowsLoaded : total;
+            var dropped = job.rowsDropped || 0;
+            return total + (dropped > 0 ? ' (' + loaded + ' loaded, ' + dropped + ' dropped)' : '');
+          }
+          return total;
+        }
+      },
+      {
+        accessor: 'status',
+        header: 'Status',
+        cell: function(info) {
+          var job = info.row.original;
+          return (
+            <span>
+              <span className={'xeplr-import-history-status xeplr-import-history-status-' + job.status}>
+                {STATUS_LABEL[job.status] || job.status}
+              </span>
+              {job.status === 'failed' && job.error && (
+                <span className="xeplr-import-history-error"> — {job.error}</span>
+              )}
+            </span>
+          );
+        }
+      },
+      {
+        accessor: 'startedAt',
+        header: 'When',
+        cell: function(info) { return formatWhen(info.getValue()); }
+      },
+      {
+        accessor: 'createdByName',
+        header: 'Created By',
+        cell: function(info) { return info.getValue() || '—'; }
+      }
+    ]
+  }
+};
+
+export default function ImportHistorySample({ jobs, loading, error, rollingBackId, deletingId, handleRollback, handleDelete }) {
+  async function onRollbackClick(job) {
+    var ok = await raiseConfirm(
+      'This deletes every row loaded into "' + job.target + '" by this import. This cannot be undone.',
+      { title: 'Rollback this import?', confirmLabel: 'Rollback', danger: true }
+    );
+    if (ok) handleRollback(job);
+  }
+
+  async function onDeleteClick(job) {
+    var message = job.status === 'completed'
+      ? 'This removes the history record only — it does NOT undo the data loaded into "' + job.target + '". Roll back first if you need to remove that data; once this record is deleted, you won\'t be able to roll it back. This cannot be undone.'
+      : 'This removes the history record for this import. This cannot be undone.';
+    var ok = await raiseConfirm(message, { title: 'Delete this import record?', confirmLabel: 'Delete', danger: true });
+    if (ok) handleDelete(job);
+  }
+
+  var rowActions = [
+    {
+      key: 'rollback',
+      label: 'Rollback',
+      variant: 'danger',
+      visible: function(job) { return job.status === 'completed'; },
+      disabled: function(job) { return rollingBackId === job.id; },
+      onClick: onRollbackClick
+    },
+    {
+      key: 'delete',
+      label: 'Delete',
+      variant: 'danger',
+      disabled: function(job) { return deletingId === job.id; },
+      onClick: onDeleteClick
+    }
+  ];
+
+  return (
+    <div className="xeplr-import-history">
+      {loading && <p className="xeplr-data-import-hint">Loading import history…</p>}
+      {error && <div className="xeplr-data-import-alert xeplr-data-import-alert-error">{error}</div>}
+
+      {!loading && jobs.length === 0 && !error && (
+        <p className="xeplr-data-import-hint">No imports yet.</p>
+      )}
+
+      {jobs.length > 0 && (
+        <XeplrTable data={jobs} schema={SCHEMA} rowActions={rowActions} pageSize={20} />
+      )}
+    </div>
+  );
+}

package/src/dataImport/designs/dataImport.css

@@ -0,0 +1,98 @@
+/* Uses @xeplr/ui-account's --xeplr-* theme tokens when available (apply
+   .xeplr-theme-light/-dark on an ancestor); falls back to the original dark
+   hex values when that stylesheet isn't loaded — same convention as
+   gridDisplayer.css. */
+
+.xeplr-data-import { display: flex; flex-direction: column; gap: 14px; color: var(--xeplr-text-primary, #e0e0e0); }
+
+.xeplr-data-import-dropzone {
+  display: block;
+  padding: 20px;
+  border: 1px dashed var(--xeplr-border-primary, #444);
+  border-radius: 8px;
+  background: var(--xeplr-bg-secondary, #222);
+  color: var(--xeplr-text-secondary, #999);
+  font-size: 13px;
+  text-align: center;
+  cursor: pointer;
+}
+.xeplr-data-import-dropzone input[type="file"] { display: none; }
+
+.xeplr-data-import-hint { font-size: 13px; color: var(--xeplr-text-secondary, #999); margin: 0; }
+
+.xeplr-data-import-alert { padding: 10px 12px; border-radius: 6px; font-size: 13px; }
+.xeplr-data-import-alert-error {
+  background: var(--xeplr-danger-bg, #3d1111);
+  color: var(--xeplr-danger, #ff6b6b);
+  border: 1px solid var(--xeplr-danger-border, #5a1a1a);
+}
+
+.xeplr-data-import-mappings { display: flex; flex-direction: column; }
+.xeplr-data-import-mapping-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 8px 0;
+  border-bottom: 1px solid var(--xeplr-border-secondary, #2a2a2a);
+}
+.xeplr-data-import-mapping-row:last-child { border-bottom: none; }
+.xeplr-data-import-mapping-check {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  flex: 0 0 160px;
+  font-size: 13px;
+  font-weight: 600;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  cursor: pointer;
+}
+.xeplr-data-import-mapping-arrow { color: var(--xeplr-text-muted, #888); flex-shrink: 0; }
+.xeplr-data-import-mapping-row input[type="text"] {
+  flex: 1;
+  min-width: 0;
+  padding: 8px 10px;
+  border: 1px solid var(--xeplr-input-border, #3a3a3a);
+  border-radius: 6px;
+  background: var(--xeplr-input-bg, #141414);
+  color: var(--xeplr-input-text, #e0e0e0);
+  font-size: 13px;
+  font-family: inherit;
+}
+.xeplr-data-import-mapping-row input[type="text"]:focus { outline: none; border-color: var(--xeplr-accent, #646cff); }
+.xeplr-data-import-mapping-row input[type="text"]:disabled { opacity: 0.5; }
+
+.xeplr-data-import-actions { display: flex; gap: 8px; }
+.xeplr-data-import-actions button {
+  padding: 9px 16px;
+  border-radius: 6px;
+  font-size: 13px;
+  font-weight: 600;
+  cursor: pointer;
+}
+.xeplr-data-import-actions button:first-child { border: none; background: var(--xeplr-accent, #646cff); color: var(--xeplr-accent-text, #fff); }
+.xeplr-data-import-actions button:last-child { border: 1px solid var(--xeplr-border-primary, #444); background: var(--xeplr-bg-secondary, #232323); color: var(--xeplr-text-primary, #e0e0e0); }
+.xeplr-data-import-actions button:disabled { opacity: 0.6; cursor: default; }
+
+.xeplr-data-import-results { display: flex; flex-direction: column; }
+.xeplr-data-import-result-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+  padding: 8px 0;
+  font-size: 13px;
+  border-bottom: 1px solid var(--xeplr-border-secondary, #2a2a2a);
+}
+.xeplr-data-import-result-row:last-child { border-bottom: none; }
+.xeplr-data-import-result-ok { color: var(--xeplr-success, #6bcc6b); }
+.xeplr-data-import-result-fail { color: var(--xeplr-danger, #ff6b6b); }
+
+.xeplr-import-history { display: flex; flex-direction: column; gap: 10px; color: var(--xeplr-text-primary, #e0e0e0); }
+
+.xeplr-import-history-status { font-weight: 600; font-size: 12px; }
+.xeplr-import-history-status-completed { color: var(--xeplr-success, #6bcc6b); }
+.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); }

package/src/dataImport/designs/index.js

@@ -0,0 +1,2 @@
+export { default as DataImportSample } from './DataImportSample.jsx';
+export { default as ImportHistorySample } from './ImportHistorySample.jsx';

package/src/dataImport/pages.jsx

@@ -0,0 +1,17 @@
+import { useDataImportController } from './useDataImportController.js';
+import { useImportHistoryController } from './useImportHistoryController.js';
+import DataImportSample from './designs/DataImportSample.jsx';
+import ImportHistorySample from './designs/ImportHistorySample.jsx';
+import { useDesignValidator, DATA_IMPORT_RULES, IMPORT_HISTORY_RULES } from './validateDesign.js';
+
+export function DataImportPage(props) {
+  var controller = useDataImportController(props);
+  var ref = useDesignValidator('DataImportPage', DATA_IMPORT_RULES);
+  return <div ref={ref}><DataImportSample {...controller} /></div>;
+}
+
+export function ImportHistoryPage(props) {
+  var controller = useImportHistoryController(props);
+  var ref = useDesignValidator('ImportHistoryPage', IMPORT_HISTORY_RULES);
+  return <div ref={ref}><ImportHistorySample {...controller} /></div>;
+}

package/src/dataImport/useDataImportController.js

@@ -0,0 +1,94 @@
+import { useState } from 'react';
+import { uploadFile } from '../fileUpload/uploadFile.js';
+import { buildInitialMappings } 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
+ *   - 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
+ *   - 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
+ *     history), it's otherwise unused by this controller.
+ *
+ * The actual file transfer is NOT app-supplied — handleFileChange sends the
+ * picked file through @xeplr/ui-utils' own uploadFile() (see
+ * fileUpload/uploadFile.js), which every app configures ONCE via
+ * configureUpload({url, getHeaders}) to point at @xeplr/base-apis' generic
+ * uploadRoute. That's what keeps this component product/app-independent: it
+ * never needs app-specific upload wiring, only the (unavoidably app-specific)
+ * "what's in this file" and "where does it go" steps after the file already
+ * has a server-side path.
+ */
+export function useDataImportController(options = {}) {
+  var [file, setFile] = useState(null);
+  var [inspecting, setInspecting] = useState(false);
+  var [inspected, setInspected] = useState(null);
+  var [mappings, setMappings] = useState([]);
+  var [committing, setCommitting] = useState(false);
+  var [results, setResults] = useState(null);
+  var [error, setError] = useState('');
+
+  function reset() {
+    setFile(null);
+    setInspected(null);
+    setMappings([]);
+    setResults(null);
+    setError('');
+  }
+
+  async function handleFileChange(e) {
+    var picked = e.target.files && e.target.files[0];
+    if (!picked) return;
+    reset();
+    setFile(picked);
+    setInspecting(true);
+    try {
+      var uploadRes = await uploadFile(picked);
+      var inspectRes = await options.onInspect(uploadRes.filePath, picked);
+      var merged = Object.assign({ filePath: uploadRes.filePath, originalName: picked.name }, inspectRes);
+      setInspected(merged);
+      setMappings(buildInitialMappings(Object.assign({ originalName: picked.name }, merged)));
+    } catch (err) {
+      setError(err.message || 'Failed to upload/inspect file');
+    } finally {
+      setInspecting(false);
+    }
+  }
+
+  function updateMapping(index, patch) {
+    setMappings(function(prev) {
+      var next = prev.slice();
+      next[index] = Object.assign({}, next[index], patch);
+      return next;
+    });
+  }
+
+  async function handleCommit() {
+    var included = mappings.filter(function(m) { return m.include; });
+    if (!inspected || included.length === 0) return;
+    setCommitting(true);
+    setError('');
+    try {
+      var payload = included.map(function(m) { return { part: m.part, target: m.target }; });
+      var res = await options.onCommit(inspected.filePath, payload, { originalName: inspected.originalName });
+      setResults((res && res.results) || res || []);
+    } catch (err) {
+      setError(err.message || 'Import failed');
+    } finally {
+      setCommitting(false);
+    }
+  }
+
+  return {
+    file, inspecting, inspected, mappings, committing, results, error,
+    handleFileChange, updateMapping, handleCommit, reset,
+    accept: options.accept,
+    targetLabel: options.targetLabel || 'Target'
+  };
+}