data_porter 0.5.0 → 0.9.0

data/app/views/data_porter/imports/index.html.erb

@@ -1,9 +1,12 @@
-<div class="data-porter">
+<div class="data-porter" data-controller="data-porter--import-form"
+     data-data-porter--import-form-sources-value="<%= @targets.map { |t| [t[:key], t[:sources]] }.to_h.to_json %>"
+     data-data-porter--import-form-params-value="<%= @targets.map { |t| [t[:key], t[:params]] }.to_h.to_json %>"
+     data-action="keydown@document->data-porter--import-form#closeModal">
   <div class="dp-header">
     <h1 class="dp-title">Imports</h1>
     <div class="dp-header__actions">
       <%= link_to "Mapping Templates", mapping_templates_path, class: "dp-btn dp-btn--secondary" %>
-      <button type="button" class="dp-btn dp-btn--primary" onclick="document.getElementById('dp-modal').classList.add('dp-modal--open')">
+      <button type="button" class="dp-btn dp-btn--primary" data-action="data-porter--import-form#openModal">
         New Import
       </button>
     </div>
@@ -45,127 +48,68 @@
     <div class="dp-empty-state">
       <div class="dp-empty-state__icon">&#128230;</div>
       <p class="dp-empty-state__text">No imports yet</p>
-      <button type="button" class="dp-btn dp-btn--primary" onclick="document.getElementById('dp-modal').classList.add('dp-modal--open')">
+      <button type="button" class="dp-btn dp-btn--primary" data-action="data-porter--import-form#openModal">
         Create your first import
       </button>
     </div>
   <% end %>
-</div>
-
-<div id="dp-modal" class="dp-modal">
-  <div class="dp-modal__backdrop" onclick="document.getElementById('dp-modal').classList.remove('dp-modal--open')"></div>
-  <div class="dp-modal__content">
-    <div class="dp-modal__header">
-      <h2 class="dp-modal__title">New Import</h2>
-      <button type="button" class="dp-modal__close" onclick="document.getElementById('dp-modal').classList.remove('dp-modal--open')">&times;</button>
-    </div>
-
-    <%= form_with model: DataPorter::DataImport.new, url: imports_path, class: "dp-modal__body", multipart: true, data: { turbo: false } do |f| %>
-      <div class="dp-field">
-        <%= f.label :target_key, "Target", class: "dp-label" %>
-        <%= f.select :target_key,
-              @targets.map { |t| [t[:label], t[:key]] },
-              { prompt: "Select a target..." },
-              id: "dp-target-select",
-              class: "dp-select",
-              data: { sources: @targets.map { |t| [t[:key], t[:sources]] }.to_h.to_json } %>
-      </div>
-
-      <div class="dp-field">
-        <%= f.label :source_type, "Source Type", class: "dp-label" %>
-        <%= f.select :source_type,
-              DataPorter.configuration.enabled_sources.map { |s| [s.to_s.upcase, s] },
-              { prompt: "Select source type..." },
-              id: "dp-source-select",
-              class: "dp-select" %>
-      </div>
-
-      <div id="dp-file-field" class="dp-field">
-        <%= f.label :file, "File", class: "dp-label" %>
-        <label class="dp-dropzone" id="dp-dropzone">
-          <input type="file" name="data_import[file]" id="dp-file-input" class="dp-dropzone__input" />
-          <div class="dp-dropzone__content">
-            <div class="dp-dropzone__icon">&#128196;</div>
-            <span class="dp-dropzone__text">Drop your file here or <strong>browse</strong></span>
-            <span class="dp-dropzone__hint">CSV, JSON, or XLSX files accepted</span>
-          </div>
-          <div class="dp-dropzone__selected" id="dp-file-name" style="display: none;"></div>
-        </label>
-      </div>
 
-      <div class="dp-modal__footer">
-        <%= f.submit "Start Import", class: "dp-btn dp-btn--primary" %>
-        <button type="button" class="dp-btn dp-btn--secondary" onclick="document.getElementById('dp-modal').classList.remove('dp-modal--open')">Cancel</button>
+  <div id="dp-modal" class="dp-modal" data-data-porter--import-form-target="modal">
+    <div class="dp-modal__backdrop" data-action="click->data-porter--import-form#closeModalClick"></div>
+    <div class="dp-modal__content">
+      <div class="dp-modal__header">
+        <h2 class="dp-modal__title">New Import</h2>
+        <button type="button" class="dp-modal__close" data-action="data-porter--import-form#closeModalClick">&times;</button>
       </div>
-    <% end %>
-  </div>
-</div>
-
-<script>
-  (function() {
-    var targetSelect = document.getElementById("dp-target-select");
-    var sourceSelect = document.getElementById("dp-source-select");
-    var fileField = document.getElementById("dp-file-field");
-    var fileInput = document.getElementById("dp-file-input");
-    var dropzone = document.getElementById("dp-dropzone");
-    var fileName = document.getElementById("dp-file-name");
 
-    function filterSources() {
-      if (!targetSelect || !sourceSelect) return;
-      var sourcesMap = JSON.parse(targetSelect.dataset.sources || "{}");
-      var allowed = sourcesMap[targetSelect.value];
-      var options = sourceSelect.options;
-      for (var i = 1; i < options.length; i++) {
-        options[i].style.display = allowed && allowed.indexOf(options[i].value) === -1 ? "none" : "";
-      }
-      if (allowed && sourceSelect.selectedIndex > 0 && allowed.indexOf(sourceSelect.value) === -1) {
-        sourceSelect.selectedIndex = 0;
-        fileField.style.display = "";
-      }
-    }
+      <%= form_with model: DataPorter::DataImport.new, url: imports_path, class: "dp-modal__body", multipart: true, data: { turbo: false } do |f| %>
+        <div class="dp-field">
+          <%= f.label :target_key, "Target", class: "dp-label" %>
+          <%= f.select :target_key,
+                @targets.map { |t| [t[:label], t[:key]] },
+                { prompt: "Select a target..." },
+                class: "dp-select",
+                data: {
+                  data_porter__import_form_target: "targetSelect",
+                  action: "data-porter--import-form#filterSources"
+                } %>
+        </div>
 
-    if (targetSelect) {
-      targetSelect.addEventListener("change", filterSources);
-    }
+        <div data-data-porter--import-form-target="paramsContainer"></div>
 
-    if (sourceSelect) {
-      sourceSelect.addEventListener("change", function() {
-        fileField.style.display = this.value === "api" ? "none" : "";
-      });
-    }
+        <div class="dp-field">
+          <%= f.label :source_type, "Source Type", class: "dp-label" %>
+          <%= f.select :source_type,
+                DataPorter.configuration.enabled_sources.map { |s| [s.to_s.upcase, s] },
+                { prompt: "Select source type..." },
+                class: "dp-select",
+                data: {
+                  data_porter__import_form_target: "sourceSelect",
+                  action: "data-porter--import-form#toggleFileField"
+                } %>
+        </div>
 
-    if (fileInput) {
-      fileInput.addEventListener("change", function() {
-        if (this.files.length > 0) {
-          fileName.textContent = this.files[0].name;
-          fileName.style.display = "";
-          dropzone.classList.add("dp-dropzone--has-file");
-        }
-      });
-    }
+        <div class="dp-field" data-data-porter--import-form-target="fileField">
+          <%= f.label :file, "File", class: "dp-label" %>
+          <label class="dp-dropzone" data-data-porter--import-form-target="dropzone"
+                 data-action="dragover->data-porter--import-form#dragover dragleave->data-porter--import-form#dragleave drop->data-porter--import-form#drop">
+            <input type="file" name="data_import[file]" class="dp-dropzone__input"
+                   data-data-porter--import-form-target="fileInput"
+                   data-action="data-porter--import-form#handleFile" />
+            <div class="dp-dropzone__content">
+              <div class="dp-dropzone__icon">&#128196;</div>
+              <span class="dp-dropzone__text">Drop your file here or <strong>browse</strong></span>
+              <span class="dp-dropzone__hint">CSV, JSON, or XLSX files accepted</span>
+            </div>
+            <div class="dp-dropzone__selected" data-data-porter--import-form-target="fileName" style="display: none;"></div>
+          </label>
+        </div>
 
-    if (dropzone) {
-      dropzone.addEventListener("dragover", function(e) {
-        e.preventDefault();
-        this.classList.add("dp-dropzone--dragover");
-      });
-      dropzone.addEventListener("dragleave", function() {
-        this.classList.remove("dp-dropzone--dragover");
-      });
-      dropzone.addEventListener("drop", function(e) {
-        e.preventDefault();
-        this.classList.remove("dp-dropzone--dragover");
-        if (e.dataTransfer.files.length > 0) {
-          fileInput.files = e.dataTransfer.files;
-          fileInput.dispatchEvent(new Event("change"));
-        }
-      });
-    }
-
-    document.addEventListener("keydown", function(e) {
-      if (e.key === "Escape") {
-        document.getElementById("dp-modal").classList.remove("dp-modal--open");
-      }
-    });
-  })();
-</script>
+        <div class="dp-modal__footer">
+          <%= f.submit "Start Import", class: "dp-btn dp-btn--primary" %>
+          <button type="button" class="dp-btn dp-btn--secondary" data-action="data-porter--import-form#closeModalClick">Cancel</button>
+        </div>
+      <% end %>
+    </div>
+  </div>
+</div>

data/app/views/data_porter/imports/new.html.erb

@@ -19,9 +19,14 @@
             { prompt: "Select a target..." },
             id: "dp-target-select-new",
             class: "dp-select",
-            data: { sources: @targets.map { |t| [t[:key], t[:sources]] }.to_h.to_json } %>
+            data: {
+              sources: @targets.map { |t| [t[:key], t[:sources]] }.to_h.to_json,
+              params: @targets.map { |t| [t[:key], t[:params]] }.to_h.to_json
+            } %>
     </div>
 
+    <div id="dp-params-container" class="dp-params-container"></div>
+
     <div class="dp-field">
       <%= f.label :source_type, "Source Type", class: "dp-label" %>
       <%= f.select :source_type,
@@ -59,6 +64,47 @@
     var fileInput = document.getElementById("dp-file-input-new");
     var dropzone = document.getElementById("dp-dropzone-new");
     var fileName = document.getElementById("dp-file-name-new");
+    var paramsContainer = document.getElementById("dp-params-container");
+    var paramsData = JSON.parse((targetSelect && targetSelect.dataset.params) || "{}");
+
+    function renderParams() {
+      if (!paramsContainer || !targetSelect) return;
+      paramsContainer.innerHTML = "";
+      var defs = paramsData[targetSelect.value] || [];
+      defs.forEach(function(p) {
+        var div = document.createElement("div");
+        div.className = "dp-field";
+        var label = document.createElement("label");
+        label.className = "dp-label";
+        label.textContent = p.label + (p.required ? " *" : "");
+        div.appendChild(label);
+        var input;
+        if (p.type === "select" && p.collection) {
+          input = document.createElement("select");
+          input.className = "dp-select";
+          var blank = document.createElement("option");
+          blank.value = "";
+          blank.textContent = "Select...";
+          input.appendChild(blank);
+          p.collection.forEach(function(opt) {
+            var o = document.createElement("option");
+            o.textContent = opt[0];
+            o.value = opt[1];
+            if (p["default"] && String(opt[1]) === String(p["default"])) o.selected = true;
+            input.appendChild(o);
+          });
+        } else {
+          input = document.createElement("input");
+          input.className = "dp-input";
+          input.type = p.type === "number" ? "number" : (p.type === "hidden" ? "hidden" : "text");
+          if (p["default"]) input.value = p["default"];
+        }
+        input.name = "data_import[config][import_params][" + p.name + "]";
+        if (p.required) input.required = true;
+        div.appendChild(input);
+        paramsContainer.appendChild(div);
+      });
+    }
 
     function filterSources() {
       if (!targetSelect || !sourceSelect) return;
@@ -75,7 +121,10 @@
     }
 
     if (targetSelect) {
-      targetSelect.addEventListener("change", filterSources);
+      targetSelect.addEventListener("change", function() {
+        filterSources();
+        renderParams();
+      });
     }
 
     if (sourceSelect) {

data/app/views/data_porter/imports/show.html.erb

@@ -45,11 +45,16 @@
   <% end %>
 
   <% if @import.previewing? %>
+    <div id="records">
     <%= raw DataPorter::Components::Preview::SummaryCards.new(report: @import.report).call %>
     <%= raw DataPorter::Components::Preview::Table.new(
           columns: @target._columns,
           records: @records
         ).call %>
+    </div>
+    <%= raw DataPorter::Components::Shared::Pagination.new(
+          page: @page, total_pages: @total_pages, base_url: import_path(@import)
+        ).call %>
 
     <div class="dp-actions">
       <%= button_to confirm_import_path(@import), method: :post, class: "dp-btn dp-btn--primary", data: { dp_submit: true } do %>
@@ -69,10 +74,15 @@
     <% duration = @import.updated_at && @import.created_at ? distance_of_time_in_words(@import.created_at, @import.updated_at) : nil %>
     <%= raw DataPorter::Components::Preview::ResultsSummary.new(report: @import.report, duration: duration).call %>
     <% if @records.any? %>
+      <div id="records">
       <%= raw DataPorter::Components::Preview::Table.new(
             columns: @target._columns,
             records: @records
           ).call %>
+      </div>
+      <%= raw DataPorter::Components::Shared::Pagination.new(
+            page: @page, total_pages: @total_pages, base_url: import_path(@import)
+          ).call %>
     <% end %>
     <div class="dp-actions">
       <%= link_to "Back to imports", imports_path, class: "dp-btn dp-btn--primary" %>

data/app/views/layouts/data_porter/application.html.erb

@@ -10,159 +10,30 @@
     {
       "imports": {
         "@hotwired/turbo": "<%= asset_path('data_porter/turbo.min.js') %>",
-        "@hotwired/stimulus": "<%= asset_path('data_porter/stimulus.min.js') %>"
+        "@hotwired/stimulus": "<%= asset_path('data_porter/stimulus.min.js') %>",
+        "data_porter/mapping_controller": "<%= asset_path('data_porter/mapping_controller.js') %>",
+        "data_porter/template_form_controller": "<%= asset_path('data_porter/template_form_controller.js') %>",
+        "data_porter/progress_controller": "<%= asset_path('data_porter/progress_controller.js') %>",
+        "data_porter/import_form_controller": "<%= asset_path('data_porter/import_form_controller.js') %>"
       }
     }
   </script>
-</head>
-<body>
-  <%= yield %>
-
   <script type="module">
     import "@hotwired/turbo"
-    import { Application, Controller } from "@hotwired/stimulus"
+    import { Application } from "@hotwired/stimulus"
+    import MappingController from "data_porter/mapping_controller"
+    import TemplateFormController from "data_porter/template_form_controller"
+    import ProgressController from "data_porter/progress_controller"
+    import ImportFormController from "data_porter/import_form_controller"
 
     const application = Application.start()
-
-    application.register("data-porter--mapping", class extends Controller {
-      static targets = ["columnSelect", "requiredWarning", "duplicateWarning", "saveTemplate"]
-      static values = { requiredColumns: Array }
-
-      connect() { this.validate() }
-
-      loadTemplate(event) {
-        const option = event.target.selectedOptions[0]
-        if (!option || !option.dataset.mapping) return
-        const mapping = JSON.parse(option.dataset.mapping)
-        this.columnSelectTargets.forEach(select => {
-          const header = select.name.match(/\[(.+)\]/)?.[1]
-          select.value = (header && mapping[header]) ? mapping[header] : ""
-        })
-        if (this.hasSaveTemplateTarget) this.saveTemplateTarget.style.display = "none"
-        this.validate()
-      }
-
-      onChange() { this.validate() }
-
-      validate() {
-        this.validateRequired()
-        this.validateDuplicates()
-      }
-
-      validateRequired() {
-        if (!this.hasRequiredWarningTarget) return
-        const selected = new Set(this.columnSelectTargets.map(s => s.value).filter(v => v !== ""))
-        const missing = this.requiredColumnsValue.filter(c => !selected.has(c.name))
-        if (missing.length > 0) {
-          this.requiredWarningTarget.textContent = "Required fields not mapped: " + missing.map(c => c.label).join(", ")
-          this.requiredWarningTarget.style.display = ""
-        } else {
-          this.requiredWarningTarget.style.display = "none"
-        }
-      }
-
-      validateDuplicates() {
-        const counts = {}
-        this.columnSelectTargets.forEach(select => {
-          if (select.value === "") return
-          counts[select.value] = (counts[select.value] || 0) + 1
-        })
-        const duplicates = new Set(Object.keys(counts).filter(k => counts[k] > 1))
-        this.columnSelectTargets.forEach(select => {
-          const row = select.closest(".dp-mapping-row")
-          if (!row) return
-          row.classList.toggle("dp-mapping-row--duplicate", select.value !== "" && duplicates.has(select.value))
-        })
-        if (this.hasDuplicateWarningTarget) {
-          if (duplicates.size > 0) {
-            this.duplicateWarningTarget.textContent = "Duplicate mappings detected for: " + [...duplicates].join(", ")
-            this.duplicateWarningTarget.style.display = ""
-          } else {
-            this.duplicateWarningTarget.style.display = "none"
-          }
-        }
-      }
-    })
-
-    application.register("data-porter--template-form", class extends Controller {
-      static targets = ["pairsContainer", "fieldSelect"]
-      static values = { columns: Object }
-
-      targetChanged(event) {
-        const columns = this.columnsValue[event.target.value] || []
-        this.fieldSelectTargets.forEach(select => this.updateOptions(select, columns))
-      }
-
-      addPair() {
-        const targetKey = this.element.querySelector("[name='mapping_template[target_key]']")?.value
-        const columns = targetKey ? (this.columnsValue[targetKey] || []) : []
-        const pair = document.createElement("div")
-        pair.className = "dp-mapping-pair"
-        pair.style.cssText = "display: flex; gap: 0.5rem; margin-bottom: 0.5rem;"
-        pair.innerHTML = this.pairHTML(columns)
-        this.pairsContainerTarget.appendChild(pair)
-      }
-
-      updateOptions(select, columns) {
-        const current = select.value
-        select.innerHTML = '<option value="">Select a field...</option>'
-        columns.forEach(([label, name]) => {
-          const opt = document.createElement("option")
-          opt.value = name
-          opt.textContent = label
-          if (name === current) opt.selected = true
-          select.appendChild(opt)
-        })
-      }
-
-      pairHTML(columns) {
-        const options = columns.map(([label, name]) => '<option value="' + name + '">' + label + "</option>").join("")
-        return '<input type="text" name="mapping_template[mapping_keys][]" placeholder="File header" class="dp-select" style="flex: 1;" />' +
-          '<select name="mapping_template[mapping_values][]" class="dp-select" style="flex: 1;" data-data-porter--template-form-target="fieldSelect">' +
-          '<option value="">Select a field...</option>' + options + "</select>"
-      }
-    })
-
-    application.register("data-porter--progress", class extends Controller {
-      static targets = ["bar", "text", "label"]
-      static values = { id: Number, url: String }
-
-      connect() {
-        this.poll()
-      }
-
-      poll() {
-        this.timer = setInterval(() => this.fetchStatus(), 1000)
-      }
-
-      async fetchStatus() {
-        try {
-          const response = await fetch(this.urlValue)
-          const data = await response.json()
-          this.updateLabel(data.status)
-          if (data.progress && data.progress.percentage !== undefined) {
-            this.barTarget.style.width = data.progress.percentage + "%"
-            this.textTarget.textContent = data.progress.percentage + "%"
-          }
-          if (!["pending", "importing", "parsing", "dry_running", "extracting_headers"].includes(data.status)) {
-            clearInterval(this.timer)
-            this.barTarget.style.width = "100%"
-            this.textTarget.textContent = "100%"
-            setTimeout(() => Turbo.visit(window.location.href, { action: "replace" }), 500)
-          }
-        } catch (e) {}
-      }
-
-      updateLabel(status) {
-        if (!this.hasLabelTarget) return
-        var labels = { pending: "Waiting...", extracting_headers: "Extracting headers...", parsing: "Parsing records...", importing: "Importing...", dry_running: "Dry run..." }
-        this.labelTarget.textContent = labels[status] || "Processing..."
-      }
-
-      disconnect() {
-        if (this.timer) clearInterval(this.timer)
-      }
-    })
+    application.register("data-porter--mapping", MappingController)
+    application.register("data-porter--template-form", TemplateFormController)
+    application.register("data-porter--progress", ProgressController)
+    application.register("data-porter--import-form", ImportFormController)
   </script>
+</head>
+<body>
+  <%= yield %>
 </body>
 </html>

data/docs/CONFIGURATION.md

@@ -28,6 +28,10 @@ DataPorter.configure do |config|
 
   # Enabled source types.
   config.enabled_sources = %i[csv json api xlsx]
+
+  # Auto-purge completed/failed imports older than this duration.
+  # Set to nil to disable. Run `rake data_porter:purge` manually or via cron.
+  config.purge_after = 60.days
 end
 ```
 
@@ -42,6 +46,7 @@ end
 | `context_builder` | `nil` | Lambda receiving the controller, returns context passed to target methods |
 | `preview_limit` | `500` | Max records shown in the preview step |
 | `enabled_sources` | `%i[csv json api xlsx]` | Source types available in the UI |
+| `purge_after` | `60.days` | Auto-purge completed/failed imports older than this duration |
 
 ## Authentication
 
@@ -68,14 +73,31 @@ config.context_builder = ->(controller) {
 
 The returned object is available as `context` in all target instance methods.
 
-## Real-time updates
+## Real-time progress
 
-DataPorter broadcasts import progress via ActionCable. The channel streams on:
+DataPorter tracks import progress via JSON polling. The Stimulus progress controller polls `GET /imports/:id/status` every second and updates an animated progress bar.
 
+The status endpoint returns:
+
+```json
+{
+  "status": "importing",
+  "progress": { "current": 42, "total": 100, "percentage": 42 }
+}
 ```
-#{cable_channel_prefix}/imports/#{import_id}
-```
 
-The default prefix is `data_porter`, so a typical stream name is `data_porter/imports/42`.
+No ActionCable or WebSocket configuration required -- it works out of the box with any deployment.
+
+## Auto-purge
+
+Old completed/failed imports can be cleaned up automatically:
+
+```bash
+# Run manually
+bin/rails data_porter:purge
+
+# Or schedule via cron (e.g. with whenever or solid_queue)
+# Removes imports older than purge_after (default: 60 days)
+```
 
-The engine ships with a Stimulus controller that automatically subscribes to the channel and updates a progress bar during parsing and importing. If ActionCable is unavailable, it falls back to polling every 3 seconds.
+Attached files are purged from ActiveStorage along with the import record.

data/docs/ROADMAP.md

@@ -0,0 +1,28 @@
+# Roadmap
+
+## v1.0 — Production-ready
+
+The goal is a gem that handles real-world imports reliably at scale.
+
+### ~~1. Records pagination~~ DONE
+
+Implemented in v0.6.0. Preview and completed pages are paginated (50 per page).
+Controller limits records loaded via `RecordPagination` concern.
+
+### ~~2. Import params~~ DONE
+
+Implemented in v0.9.0. Targets declare `params` with a DSL (`:select`, `:text`,
+`:number`, `:hidden`). Values stored in `config["import_params"]`, accessible
+via `import_params` in all target instance methods. See [Targets docs](TARGETS.md#params--).
+
+---
+
+## v2+ (future)
+
+- Scoped imports (filter index by user/tenant)
+- Webhooks / callbacks on import completion
+- Batch persist (`insert_all` support)
+- Resume / partial retry
+- Scheduled imports (recurring API source)
+- i18n
+- Dashboard stats

data/docs/TARGETS.md

@@ -5,20 +5,23 @@ Targets are plain Ruby classes in `app/importers/` that inherit from `DataPorter
 ## Generator
 
 ```bash
-bin/rails generate data_porter:target ModelName column:type[:required] ...
+bin/rails generate data_porter:target ModelName column:type[:required] ... [--sources csv xlsx]
 ```
 
 Examples:
 
 ```bash
-bin/rails generate data_porter:target User email:string:required name:string age:integer
-bin/rails generate data_porter:target Product name:string price:decimal
+bin/rails generate data_porter:target User email:string:required name:string age:integer --sources csv xlsx
+bin/rails generate data_porter:target Product name:string price:decimal --sources csv
+bin/rails generate data_porter:target Order order_number:string total:decimal
 ```
 
 Column format: `name:type[:required]`
 
 Supported types: `string`, `integer`, `decimal`, `boolean`, `date`.
 
+The `--sources` option specifies which source types the target accepts (default: `csv`). The UI will only show these sources when the target is selected.
+
 ## Class-level DSL
 
 ```ruby
@@ -52,6 +55,12 @@ class OrderTarget < DataPorter::Target
   deduplicate_by :order_number
 
   dry_run_enabled
+
+  params do
+    param :warehouse_id, type: :select, label: "Warehouse", required: true,
+          collection: -> { Warehouse.pluck(:name, :id) }
+    param :currency, type: :text, default: "USD"
+  end
 end
 ```
 
@@ -120,8 +129,50 @@ deduplicate_by :first_name, :last_name
 
 Enables dry run mode for this target. A "Dry Run" button appears in the preview step. Dry run executes the full import pipeline (transform, validate, persist) inside a rolled-back transaction, giving a validation report without modifying the database.
 
+### `params { ... }`
+
+Declares extra form fields shown when this target is selected in the import form. Values are stored in `config["import_params"]` and accessible via `import_params` in all instance methods.
+
+```ruby
+params do
+  param :hotel_id, type: :select, label: "Hotel", required: true,
+        collection: -> { Hotel.pluck(:name, :id) }
+  param :currency, type: :text, label: "Currency", default: "EUR"
+  param :batch_size, type: :number, label: "Batch Size", default: "100"
+  param :tenant_id, type: :hidden, default: "abc123"
+end
+```
+
+Each param accepts:
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `name` | Symbol | (required) | Param identifier |
+| `type` | Symbol | `:text` | One of `:select`, `:text`, `:number`, `:hidden` |
+| `required` | Boolean | `false` | Validated on import creation, shown with `*` in the form |
+| `label` | String | Humanized name | Display label in the form |
+| `default` | String | `nil` | Pre-filled value in the form |
+| `collection` | Lambda | `nil` | For `:select` type -- returns `[[label, value], ...]` |
+
+Collection lambdas are evaluated when the form loads, not at boot time. This ensures fresh data (e.g., newly created hotels appear immediately).
+
 ## Instance Methods
 
+### `import_params`
+
+Returns a hash of the import params values set by the user in the form. Available in all instance methods (`persist`, `transform`, `validate`, `after_import`, `on_error`). Defaults to `{}` when no params are declared.
+
+```ruby
+def persist(record, context:)
+  Guest.create!(
+    record.attributes.merge(
+      hotel_id: import_params["hotel_id"],
+      currency: import_params["currency"]
+    )
+  )
+end
+```
+
 Override these in your target to customize behavior.
 
 ### `transform(record)`