data_porter 0.1.0 → 0.4.0

data/docs/blog/SERIES.md

@@ -1,154 +0,0 @@
----
-series: "Building DataPorter - A Data Import Engine for Rails"
-author: ""
-repo: ""
-status: complete
----
-
-# Series Plan
-
-## Target audience
-Ruby/Rails developers (intermediate+) interested in gem architecture, Rails engines, and clean DSL design.
-
-## Series structure
-Each article: ~5-8 min read, one clear concept, real code, decisions explained.
-
----
-
-## Articles
-
-### Part 1 — Why build a data import engine?
-- **Tasks:** None (intro)
-- **Hook:** The repetitive import pattern in Rails apps
-- **Covers:** Problem statement, existing solutions (maintenance_tasks, activeadmin_import), why a new gem, what we'll build (3-step workflow diagram)
-- **Key decisions:** Mountable engine vs. lib, isolate_namespace, target audience
-- **File:** `docs/blog/001-why-build-a-data-import-engine.md`
-- **Status:** draft
-
-### Part 2 — Scaffolding a Rails Engine gem
-- **Tasks:** #1
-- **Hook:** `bundle gem` is just the start
-- **Covers:** Gem structure, Engine setup, isolate_namespace, directory tree, gemspec dependencies
-- **Key decisions:** Why isolate_namespace, directory conventions, dependency choices (store_model, phlex, turbo)
-- **File:** `docs/blog/002-scaffolding-a-rails-engine.md`
-- **Status:** draft
-
-### Part 3 — Configuration DSL: making the gem flexible
-- **Tasks:** #2
-- **Hook:** A good gem adapts to any host app
-- **Covers:** Configuration singleton pattern, DSL with `configure` block, sensible defaults, context_builder lambda
-- **Key decisions:** Why not Rails config, lambda vs block for context, what to make configurable vs. convention
-- **File:** `docs/blog/003-configuration-dsl.md`
-- **Status:** draft
-
-### Part 4 — Modeling import data with StoreModel & JSONB
-- **Tasks:** #3, #4
-- **Hook:** Storing structured data without extra tables
-- **Covers:** StoreModel gem, ImportRecord/Error/Report models, JSONB attributes, TypeValidator
-- **Key decisions:** JSONB vs. separate tables, store_model vs. hand-rolled, validation strategy (column-level vs DB-level)
-- **File:** `docs/blog/004-store-model-jsonb.md`
-- **Status:** draft
-
-### Part 5 — Designing a Target DSL
-- **Tasks:** #5, #6
-- **Hook:** One file = one import type, zero boilerplate
-- **Covers:** Target base class, class-level DSL (label, model, columns, csv_mapping), Registry pattern, auto-discovery
-- **Key decisions:** DSL design (class methods vs. instance), class_attribute vs. class instance vars, hook pattern for extensibility
-- **File:** `docs/blog/005-target-dsl.md`
-- **Status:** draft
-
-### Part 6 — Parsing CSV data with Sources
-- **Tasks:** #7, #8
-- **Hook:** The first end-to-end flow
-- **Covers:** DataImport model, migration, Source base class, CSV source, ActiveStorage integration, column mapping
-- **Key decisions:** Polymorphic user association, enum state machine, auto-mapping vs explicit mapping
-- **File:** `docs/blog/006-parsing-csv-sources.md`
-- **Status:** draft
-
-### Part 7 — The Orchestrator: coordinating the import workflow
-- **Tasks:** #9, #10
-- **Hook:** The brain of the engine
-- **Covers:** Orchestrator class (parse! and import!), state transitions, error handling per-record, ActiveJob integration
-- **Key decisions:** Why an orchestrator (not controller logic), transaction boundaries, error recovery strategy
-- **File:** `docs/blog/007-orchestrator.md`
-- **Status:** draft
-
-### Part 8 — Real-time progress with ActionCable & Stimulus
-- **Tasks:** #11, #14
-- **Hook:** Users hate staring at a spinner with no feedback
-- **Covers:** Broadcaster service, ImportChannel, Stimulus controller, progress bar updates, auto-reload on completion
-- **Key decisions:** ActionCable vs. polling vs. SSE, channel naming strategy, Stimulus vs. Turbo Streams
-- **File:** `docs/blog/008-actioncable-stimulus.md`
-- **Status:** draft
-
-### Part 9 — Building the UI with Phlex & Tailwind
-- **Tasks:** #13
-- **Hook:** Auto-generated preview tables from a DSL
-- **Covers:** Phlex components, scoped Tailwind (dp- prefix), preview table with dynamic columns, status badges, CSS custom properties for theming
-- **Key decisions:** Phlex vs. ERB/ViewComponent, Tailwind prefix strategy, how to not pollute host app styles
-- **File:** `docs/blog/009-phlex-ui-components.md`
-- **Status:** draft
-
-### Part 10 — Controllers & routing in a Rails Engine
-- **Tasks:** #12
-- **Hook:** Engine controllers are tricky — here's the clean way
-- **Covers:** ImportsController, inheriting from host's parent controller, engine routes, strong params, Turbo integration
-- **Key decisions:** Dynamic parent controller inheritance, route namespacing, how auth flows from host to engine
-- **File:** `docs/blog/010-controllers-routing.md`
-- **Status:** draft
-
-### Part 11 — Generators: install & target scaffolding
-- **Tasks:** #15, #16
-- **Hook:** Great gems install in one command
-- **Covers:** Install generator (migration, initializer, routes), Target generator (column parsing, template), Rails::Generators API
-- **Key decisions:** What to generate vs. what to configure, template format (ERB .tt), route injection strategy
-- **File:** `docs/blog/011-generators.md`
-- **Status:** draft
-
-### Part 12 — Adding JSON & API sources
-- **Tasks:** #18, #19
-- **Hook:** CSV is just the beginning
-- **Covers:** JSON source (file + raw text), API source (HTTP client, params injection), source plugin architecture
-- **Key decisions:** Source abstraction design, how to handle auth headers, response_root extraction
-- **File:** `docs/blog/012-json-api-sources.md`
-- **Status:** draft
-
-### Part 13 — Testing a Rails Engine with RSpec
-- **Tasks:** #17
-- **Hook:** Testing an engine is different from testing an app
-- **Covers:** Dummy app setup, spec organization, testing StoreModels, mocking ActiveStorage, testing jobs, controller specs
-- **Key decisions:** Dummy app vs. shared examples, factory vs. fixture, what to unit test vs. integration test
-- **File:** `docs/blog/013-testing-rails-engine.md`
-- **Status:** draft
-
-### Part 14 — Dry Run: validate before you persist
-- **Tasks:** #20
-- **Hook:** Preview catches column errors, dry-run catches DB errors
-- **Covers:** Transaction + rollback pattern, enriching records with DB errors, DryRunJob, UI integration
-- **Key decisions:** Why two validation layers, transaction rollback approach, when to offer dry-run
-- **File:** `docs/blog/014-dry-run.md`
-- **Status:** draft
-
-### Part 15 — Publishing the gem & retrospective
-- **Tasks:** None (wrap-up)
-- **Hook:** From idea to rubygems.org
-- **Covers:** Gemspec final polish, CHANGELOG, versioning, publishing, series recap, what worked, what we'd do differently
-- **Key decisions:** Semantic versioning strategy, open source considerations
-- **File:** `docs/blog/015-publishing-retro.md`
-- **Status:** draft
-
-### Part 16 — ERB View Templates: Composing Phlex Components
-- **Tasks:** None (view layer completion)
-- **Hook:** Phlex components are pure Ruby. ERB is what the browser sees. The glue is `.call`.
-- **Covers:** ERB templates composing Phlex, has_one_attached bugfix, ActiveStorage test setup, view testing in Rails 8, plain CSS stylesheet
-- **Key decisions:** raw component.call vs phlex-rails, plain CSS vs build step, view test infrastructure
-- **File:** `docs/blog/016-erb-view-templates.md`
-- **Status:** draft
-
-### Part 17 — Showcase & Final Retrospective
-- **Tasks:** None (series finale)
-- **Hook:** 17 articles, 22 components, one complete gem. DataPorter in action.
-- **Covers:** Full workflow walkthrough with screenshots, architecture overview, series recap, lessons learned, what's next
-- **Key decisions:** N/A (retrospective)
-- **File:** `docs/blog/017-showcase-final-retro.md`
-- **Status:** draft

data/lib/data_porter/components/failure_alert.rb

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-
-module DataPorter
-  module Components
-    class FailureAlert < Base
-      def initialize(report:)
-        super()
-        @report = report
-      end
-
-      def view_template
-        div(class: "dp-alert dp-alert--danger") do
-          @report.error_reports.each do |err|
-            p { err.message }
-          end
-        end
-      end
-    end
-  end
-end

data/lib/data_porter/components/preview_table.rb

@@ -1,54 +0,0 @@
-# frozen_string_literal: true
-
-module DataPorter
-  module Components
-    class PreviewTable < Base
-      def initialize(columns:, records:)
-        super()
-        @columns = columns
-        @records = records
-      end
-
-      def view_template
-        div(class: "dp-preview-table") do
-          table(class: "dp-table") do
-            render_header
-            render_body
-          end
-        end
-      end
-
-      private
-
-      def render_header
-        thead do
-          tr do
-            th { "#" }
-            th { "Status" }
-            @columns.each { |col| th { col.label } }
-            th { "Errors" }
-          end
-        end
-      end
-
-      def render_body
-        tbody do
-          @records.each { |record| render_row(record) }
-        end
-      end
-
-      def render_row(record)
-        tr(class: "dp-row--#{record.status}") do
-          td { record.line_number.to_s }
-          td { record.status }
-          @columns.each { |col| td { record.data[col.name.to_s].to_s } }
-          td(class: "dp-errors") { error_messages(record) }
-        end
-      end
-
-      def error_messages(record)
-        record.errors_list.map(&:message).join(", ")
-      end
-    end
-  end
-end

data/lib/data_porter/components/progress_bar.rb

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-module DataPorter
-  module Components
-    class ProgressBar < Base
-      def initialize(import_id:)
-        super()
-        @import_id = import_id
-      end
-
-      def view_template
-        div(class: "dp-progress", **stimulus_controller_attrs) do
-          render_bar
-        end
-      end
-
-      private
-
-      def render_bar
-        div(class: "dp-progress-bar", data_data_porter__progress_target: "bar", style: "width: 0%") do
-          span(data_data_porter__progress_target: "text") { "0%" }
-        end
-      end
-
-      def stimulus_controller_attrs
-        {
-          data_controller: "data-porter--progress",
-          data_data_porter__progress_id_value: @import_id.to_s
-        }
-      end
-    end
-  end
-end

data/lib/data_porter/components/results_summary.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-module DataPorter
-  module Components
-    class ResultsSummary < Base
-      def initialize(report:)
-        super()
-        @report = report
-      end
-
-      def view_template
-        div(class: "dp-results") do
-          p { "Created: #{@report.imported_count}" }
-          p { "Errors: #{@report.errored_count}" }
-        end
-      end
-    end
-  end
-end

data/lib/data_porter/components/status_badge.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-module DataPorter
-  module Components
-    class StatusBadge < Base
-      def initialize(status:)
-        super()
-        @status = status.to_s
-      end
-
-      def view_template
-        span(class: "dp-badge dp-badge--#{@status}") { @status.capitalize }
-      end
-    end
-  end
-end

data/lib/data_porter/components/summary_cards.rb

@@ -1,30 +0,0 @@
-# frozen_string_literal: true
-
-module DataPorter
-  module Components
-    class SummaryCards < Base
-      def initialize(report:)
-        super()
-        @report = report
-      end
-
-      def view_template
-        div(class: "dp-summary-cards") do
-          card("dp-card--complete", @report.complete_count, "Ready")
-          card("dp-card--partial", @report.partial_count, "Incomplete")
-          card("dp-card--missing", @report.missing_count, "Missing")
-          card("dp-card--duplicate", @report.duplicate_count, "Duplicates")
-        end
-      end
-
-      private
-
-      def card(css_class, count, label)
-        div(class: "dp-card #{css_class}") do
-          strong { count.to_s }
-          plain " #{label}"
-        end
-      end
-    end
-  end
-end