data_porter 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46a9ae914232272194aaa961ed2619a423e2fcbbe9b5dc4dbdb2762bbcdb7129
-  data.tar.gz: 4de6b7f13955136df74552b6788792b3f9e8ba0b201e8b0fa25000e28294e13b
+  metadata.gz: '0439ba2634bbf47987015524141c3f961b54c362d234dcaeecc7811895c4ec34'
+  data.tar.gz: b4b2daf3519743518b2119b75863ca83114db258599fa2026e1b7a2ae844668e
 SHA512:
-  metadata.gz: 0af51f459c999859b1ef723787998134e96a371bfe25c4e99a086a38cd787e35f4c8b2e58331b5594a1baeb7bc0c8220d0ccd5a9c2738f0cbabc1cc69021a754
-  data.tar.gz: 735f5bc4d814f7e641fd8e2d9498487ddf75a5ce784f40439fbcfcdd7a995b131e243538dd261ea5d5b4494148a0035b83b7c5bac924de2f9279f2a019dd6af5
+  metadata.gz: b2ddc41b18ab043cbabb97518594ec27a0d1ec4ea0f4f1e542a6dde664c6914d6d1b61c609e6436d9a9bd741298c31766c623886eb3964a417b9a5ebec532b44
+  data.tar.gz: 2fe7cc8d5910005f86b9198db007afc406bb186d933d0ff1a5e4c147fab191ade9386550fdbb5b85f4756c6795da979f81da5b4681782c027f7901763f1dd972

data/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.0] - 2026-02-19
+
+### Breaking
+
+- **Default parent controller changed to `ActionController::Base`** -- Engine controllers no longer inherit from `ApplicationController` by default, avoiding conflicts with authorization gems (Pundit, CanCanCan, etc.). Set `config.parent_controller = "ApplicationController"` to restore the previous behavior
+- **Engine routes mounted at root** -- `resources :imports` now uses `path: "/"` so the mount point controls the full URL (e.g. `mount DataPorter::Engine, at: "/imports"` gives `/imports`, not `/imports/imports`)
+
+### Added
+
+- **Back to mapping** -- `back_to_mapping` action resets a previewing import to the mapping step, preserving file headers and column mapping for re-mapping
+- **Saved mapping persistence** -- Mapping form restores previously saved column mapping instead of resetting to defaults
+
+### Changed
+
+- 423 RSpec examples (up from 413), 0 failures
+
 ## [1.1.0] - 2026-02-08
 
 ### Added

data/README.md

@@ -1,23 +1,10 @@
 # DataPorter
 
-> [!CAUTION]
-> **This gem is under active development and not yet production-ready.**
-> APIs and features may change without notice. Use at your own risk.
-
 A mountable Rails engine for data import workflows: **Upload**, **Map**, **Preview**, **Import**.
 
 Supports CSV, JSON, XLSX, and API sources with a declarative DSL for defining import targets. Business-agnostic by design -- all domain logic lives in your host app.
 
-<table>
-  <tr>
-    <td><img src="docs/screenshots/index-with-previewing.jpg" width="400" alt="Import list with status badges" /></td>
-    <td><img src="docs/screenshots/modal-new-import.jpg" width="400" alt="New import modal with dropzone" /></td>
-  </tr>
-  <tr>
-    <td><img src="docs/screenshots/mapping.jpg" width="400" alt="Interactive column mapping with templates" /></td>
-    <td><img src="docs/screenshots/preview.jpg" width="400" alt="Preview with summary cards and data table" /></td>
-  </tr>
-</table>
+![DataPorter demo](docs/screenshots/demo_fast.gif)
 
 ## Features
 
@@ -142,7 +129,7 @@ pending -> parsing -> previewing -> importing -> completed
 git clone https://github.com/SerylLns/data_porter.git
 cd data_porter
 bin/setup
-bundle exec rspec     # 405 specs
+bundle exec rspec     # 413 specs
 bundle exec rubocop   # 0 offenses
 ```
 

data/app/controllers/data_porter/concerns/mapping_management.rb

@@ -12,7 +12,7 @@ module DataPorter
         columns = target._columns || []
         @file_headers = @import.config["file_headers"] || []
         @target_columns = columns.map { |c| [c.label, c.name.to_s, c.required] }
-        @default_mapping = (target._csv_mappings || {}).transform_values(&:to_s)
+        @default_mapping = saved_or_default_mapping(target)
         @templates = load_templates
       end
 
@@ -23,6 +23,13 @@ module DataPorter
         scope.for_target(@import.target_key)
       end
 
+      def saved_or_default_mapping(target)
+        saved = @import.config&.dig("column_mapping")
+        return saved if saved.present?
+
+        (target._csv_mappings || {}).transform_values(&:to_s)
+      end
+
       def save_column_mapping
         merged = (@import.config || {}).merge("column_mapping" => permitted_column_mapping)
         @import.update!(config: merged, status: :pending)

data/app/controllers/data_porter/imports_controller.rb

@@ -9,7 +9,8 @@ module DataPorter
 
     layout "data_porter/application"
 
-    before_action :set_import, only: %i[show parse confirm cancel dry_run update_mapping status export_rejects destroy]
+    before_action :set_import, only: %i[show parse confirm cancel dry_run update_mapping
+                                        status export_rejects destroy back_to_mapping]
     before_action :load_targets, only: %i[index new create]
 
     def index
@@ -63,6 +64,11 @@ module DataPorter
       redirect_to imports_path
     end
 
+    def back_to_mapping
+      @import.reset_to_mapping!
+      redirect_to import_path(@import)
+    end
+
     def dry_run
       @import.update!(status: :pending)
       DataPorter::DryRunJob.perform_later(@import.id)

data/app/models/data_porter/data_import.rb

@@ -53,6 +53,15 @@ module DataPorter
       records.group_by(&:status).transform_values(&:count)
     end
 
+    def reset_to_mapping!
+      update!(
+        status: :mapping,
+        records: [],
+        report: StoreModels::Report.new,
+        config: (config || {}).except("progress")
+      )
+    end
+
     def file_based?
       %w[csv xlsx].include?(source_type)
     end

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

@@ -65,6 +65,10 @@
           Dry Run
         <% end %>
       <% end %>
+      <% if @import.file_based? %>
+        <%= button_to "Back to Mapping", back_to_mapping_import_path(@import),
+              method: :post, class: "dp-btn dp-btn--secondary" %>
+      <% end %>
       <%= button_to "Cancel", cancel_import_path(@import),
             method: :post, class: "dp-btn dp-btn--danger" %>
     </div>

data/bookmarklet.md

@@ -0,0 +1,217 @@
+---
+title: "Building a Product Clipper Bookmarklet with Shadow DOM and Structured Data"
+published: false
+tags: javascript, webdev, architecture, bookmarklet
+---
+
+# Building a Product Clipper Bookmarklet with Shadow DOM and Structured Data
+
+We’re in 2008.
+
+The iPhone 3G just dropped. Facebook crosses 100 million users. Bitcoin quietly appears on a cryptography mailing list. The web is shifting.
+
+And while the world is obsessing over apps and platforms… we’re going back to something beautifully simple.
+
+**A bookmarklet.**
+
+No extension store review.  
+No packaging.  
+No deployment delays.
+
+Just a small piece of JavaScript living inside a browser bookmark — capable of injecting a clean, isolated UI into any e-commerce page, detecting product data automatically, and sending it to your backend.
+
+One click. Any product page. Instant extraction.
+
+Here’s how the architecture works.
+
+---
+
+## High-Level Architecture
+
+The clipper follows a simple execution model:
+
+1. The bookmarklet injects a remote script into the current page.
+2. The script scans the DOM using multiple detection strategies.
+3. A sidebar panel renders inside a Shadow DOM (fully isolated).
+4. Detected products are visually highlighted.
+5. The user selects items to import.
+6. Selected data is sent to the backend for processing.
+
+No browser extension. No build complexity. Just runtime execution.
+
+---
+
+## Why a Bookmarklet?
+
+For a user-triggered action ("Import this page"), a bookmarklet offers strong trade-offs:
+
+|             | Bookmarklet           | Browser Extension                |
+| ----------- | --------------------- | -------------------------------- |
+| Install     | Drag a link           | Store review required            |
+| Updates     | Instant (server-side) | Requires store re-approval       |
+| Permissions | None                  | Explicit permission prompts      |
+| Maintenance | Single hosted file    | Multi-file manifest architecture |
+
+If your tool runs only when explicitly triggered, a bookmarklet is often the leanest solution.
+
+---
+
+## Product Detection Strategy
+
+No single detection method works across all e-commerce sites.
+
+A robust clipper layers multiple strategies, ordered by confidence:
+
+- **Structured Data (JSON-LD)**  
+  Many sites expose `schema.org/Product` data for SEO.
+- **Microdata attributes**
+- **OpenGraph metadata**
+- **Heuristic DOM scanning**
+- **URL pattern matching (fallback)**
+
+The key principle is:
+
+> Prefer high-confidence structured data, then gracefully degrade.
+
+### Example: Extracting JSON-LD Products
+
+```javascript
+function extractFromJsonLd() {
+  const scripts = document.querySelectorAll(
+    'script[type="application/ld+json"]',
+  );
+  const products = [];
+
+  scripts.forEach((script) => {
+    try {
+      const data = JSON.parse(script.textContent);
+      // Traverse recursively and collect Product objects
+      collectProducts(data, products);
+    } catch (e) {}
+  });
+
+  return products;
+}
+```
+
+In practice, you normalize URLs, merge duplicates, and score sources by confidence before presenting results.
+
+The goal is reliability, not perfection.
+
+---
+
+## Shadow DOM: Isolation Is Non-Negotiable
+
+Injecting UI into arbitrary websites is dangerous.
+
+CSS resets, `!important` rules, framework styles — they will break your interface.
+
+Shadow DOM solves this by creating an isolated rendering tree:
+
+```javascript
+const host = document.createElement("div");
+document.body.appendChild(host);
+
+const shadow = host.attachShadow({ mode: "open" });
+shadow.innerHTML = `
+  <style>
+    :host { all: initial; font-family: system-ui; }
+    .panel { position: fixed; right: 0; top: 0; }
+  </style>
+  <div class="panel">Clipper UI</div>
+`;
+```
+
+Key principle:
+
+> Your UI must behave identically on Shopify, Magento, custom React apps, or legacy PHP pages.
+
+Isolation is mandatory.
+
+---
+
+## Visual Feedback & Interaction Control
+
+When products are detected, highlighting them directly on the page improves user confidence.
+
+Because many e-commerce sites attach their own click handlers (analytics, routing, SPA navigation), event handling must be carefully managed.
+
+Best practice:
+
+- Use capture phase listeners
+- Prevent unintended navigation
+- Clean up all listeners and styles on teardown
+
+A clipper should leave **zero traces** after closing.
+
+---
+
+## Backend Communication
+
+Once items are selected, the clipper sends a structured payload to your backend.
+
+The backend typically:
+
+- Normalizes URLs
+- Deduplicates products
+- Associates them with a source domain
+- Triggers downstream processing (price tracking, enrichment, etc.)
+
+Security considerations:
+
+- Use scoped, short-lived API tokens
+- Never expose sensitive credentials
+- Sanitize all extracted DOM content before rendering
+
+---
+
+## Limitations
+
+A bookmarklet runs inside the page’s context. That comes with constraints.
+
+### Content Security Policy (CSP)
+
+Strict `script-src` headers can block injected scripts entirely.
+There is no client-side workaround. A browser extension is required in those cases.
+
+### Single Page Applications (SPAs)
+
+React/Next.js apps often load content asynchronously.
+Mutation observers or delayed scans improve detection reliability.
+
+### Bot Protection (Backend)
+
+While the bookmarklet runs in the user’s real browser session, backend scraping of submitted URLs may face anti-bot systems.
+That is a server-side concern.
+
+---
+
+## Legal & Ethical Considerations
+
+If you build a commercial tool around product extraction:
+
+- Only collect publicly visible data
+- Do not bypass authentication or CAPTCHAs
+- Respect rate limits
+- Be transparent about data usage
+- Review relevant laws (CFAA, GDPR, local regulations)
+
+User-initiated clipping is typically lower risk than automated crawling, but not risk-free.
+
+---
+
+## Lessons Learned
+
+1. **Isolation first.** Shadow DOM prevents 90% of UI conflicts.
+2. **Layered detection beats single heuristics.**
+3. **Keep it framework-free.** Dependencies increase fragility.
+4. **Design for hostile environments.** You do not control the host page.
+5. **Simplicity wins.** A single hosted file can outperform complex extension architectures.
+
+---
+
+A bookmarklet is not flashy.
+
+But when designed correctly, it becomes a powerful bridge between arbitrary web pages and your product.
+
+Sometimes the most effective architecture is the one that avoids complexity entirely.

data/config/routes.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
 DataPorter::Engine.routes.draw do
-  resources :imports, only: %i[index new create show destroy] do
+  resources :imports, path: "/", only: %i[index new create show destroy] do
     member do
       post :parse
       post :confirm
       post :cancel
+      post :back_to_mapping
       post :dry_run
       patch :update_mapping
       get :status
@@ -13,5 +14,5 @@ DataPorter::Engine.routes.draw do
     end
   end
 
-  resources :mapping_templates, except: :show
+  resources :mapping_templates
 end

data/lib/data_porter/configuration.rb

@@ -16,8 +16,8 @@ module DataPorter
                   :transaction_mode
 
     def initialize
-      @parent_controller = "ApplicationController"
-      @queue_name = :imports
+      @parent_controller = "ActionController::Base"
+      @queue_name = :default
       @storage_service = :local
       @cable_channel_prefix = "data_porter"
       @context_builder = nil

data/lib/data_porter/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DataPorter
-  VERSION = "1.1.0"
+  VERSION = "2.0.0"
 end

data/lib/generators/data_porter/install/templates/initializer.rb

@@ -2,11 +2,12 @@
 
 DataPorter.configure do |config|
   # Parent controller for the engine's controllers to inherit from.
-  # This controls authentication, layouts, and helpers.
+  # Defaults to ActionController::Base. Set to "ApplicationController" to inherit
+  # authentication, layouts, and helpers from your app.
   # config.parent_controller = "ApplicationController"
 
   # ActiveJob queue name for import jobs.
-  # config.queue_name = :imports
+  # config.queue_name = :default
 
   # ActiveStorage service for uploaded files.
   # config.storage_service = :local

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: data_porter
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Seryl Lounis
@@ -139,6 +139,7 @@ files:
 - app/views/data_porter/mapping_templates/index.html.erb
 - app/views/data_porter/mapping_templates/new.html.erb
 - app/views/layouts/data_porter/application.html.erb
+- bookmarklet.md
 - config/routes.rb
 - lib/data_porter.rb
 - lib/data_porter/broadcaster.rb