@ingestro/importer-react 4.9.1 → 4.9.2

package/README.md

@@ -100,6 +100,64 @@ In this example:
 
 For a comprehensive guide on setting up and customizing the importer, refer to the [First Steps](https://docs.ingestro.com/sdk/start/) documentation.
 
+### Hook-based usage (`useDataImporter`)
+
+`useDataImporter` is a hook-based alternative to the `DataImporter` component. It
+accepts the **exact same configuration** as `<DataImporter />` (a superset of
+`IConfigureAPI`, including `stepHandler`, the lifecycle callbacks and the
+`onUploadSuccess` / `onUploadError` convenience callbacks) and mounts the same UI
+into the element you attach the returned `ref` to.
+
+```jsx
+import { useDataImporter } from '@ingestro/importer-react';
+
+function ImportButton() {
+  const { ref, open, isReady, isUploading, error } = useDataImporter({
+    licenseKey: 'Your License Key',
+    settings: {
+      identifier: 'product_data',
+      columns: [
+        { label: 'Product ID', key: 'product_id' },
+        { label: 'Article Name', key: 'article_name' },
+      ],
+    },
+    onUploadSuccess: () => analytics.track('file-upload-success'),
+    onUploadError: ({ type, message }) => analytics.track('file-upload-error', { type, message }),
+    onResults: (results, errors, complete) => {
+      console.log('Imported Data:', results);
+      complete();
+    },
+  });
+
+  return (
+    <>
+      {/* Mounting this element renders the same UI as <DataImporter /> */}
+      <div ref={ref} />
+
+      <button onClick={open} disabled={!isReady || isUploading}>
+        Upload file
+      </button>
+
+      {error ? <p>{error.message}</p> : null}
+    </>
+  );
+}
+```
+
+The hook returns:
+
+- **ref**: attach to an element (e.g. `<div ref={ref} />`) to mount the importer.
+- **open()**: opens the importer (file picker / modal), mirroring the launcher button.
+- **reload()**: reloads this instance (proxies `ImporterSession.reload` for its `identifier`).
+- **isReady**: `true` once the instance is authorized/verified (parity with `ImporterSession.verify`).
+- **isUploading**: `true` while a selected file is being parsed / uploaded.
+- **error**: unified `{ type, message }` for verification or upload failures.
+
+Because each hook instance owns its own container and `settings.identifier`,
+multiple `useDataImporter` instances can coexist on one page and each remains
+individually targetable by [`ImporterSession`](https://docs.ingestro.com/sdk/dynamic-import/)
+(`parse` / `upload` / `start` / `verify` / `reload`) using its `identifier`.
+
 ## Advanced Configuration
 
 ### Settings & Configuration

package/index.d.ts

@@ -2001,6 +2001,21 @@ export type LanguageType =
 
 export declare const DataImporter: (props: ConfigureAPI) => JSX.Element;
 
+export type UseDataImporterConfig = ConfigureAPI;
+
+export type UseDataImporterReturn = {
+  ref: (element: HTMLDivElement | null) => void;
+  open: () => void;
+  reload: () => void;
+  isReady: boolean;
+  isUploading: boolean;
+  error: { type: string; message: string } | null;
+};
+
+export declare const useDataImporter: (
+  config: UseDataImporterConfig
+) => UseDataImporterReturn;
+
 export type DynamicStepValues =
   | 'header'
   | 'mapping'