Module-specific components for the bulk screens. Global components come from
00-shared/03_Component_Library.md ; this file defines only what is bulk-
specific and names the global components each screen composes.
Component Used by Purpose
FileDropZoneSS1 drag-drop + browse CSV picker ImportStepperSS1-SS4 upload → preview → confirm → result CSVPreviewTableSS2 header map + sample rows ColumnChipSS2 required / optional / unknown header tag ContractAlertSS2 blocking vs non-blocking header warnings ImportSummaryCardSS4 counts + status hero ErrorReviewTableSS4 per-row error list, grouped, paged ErrorRowTileSS4 single failed row (mobile) ErrorGroupChipSS4 duplicates / references / format grouping ImportProgressPanelSS4 in-flight honesty panel (indeterminate) ExportCardSS5 entity picker + download
Property Value
Inputs onFile(File), accept=".csv", maxRowsHint (1000), busyStates idle / hover (highlight) / picking / parsing (spinner) / error (message) / disabled Behaviour native file picker on click; drag-drop on desktop; parse in isolate on selection (15 §4 ); strips UTF-8 BOM; detects non-UTF-8 → error guidance (14 §2 ) a11y exposed as a button with label "Choose CSV file"; drop target semantics; parse failure via live region Motion m-fast border glow on hover, shake on error (00-shared/08 )
Four steps: Upload · Preview · Confirm · Result. Current step filled;
completed steps show check. Compact horizontal on desktop, top-of-card on
phone. Steps are not independently clickable (wizard state lives in the
cubit, 13 ); Back buttons inside each screen are the navigation.
Property Value
Data headers (with per-header classification), first 10 rows, total rows Row numbering physical line numbers (header = 1) — must equal server rowNumber (bulk-import.service.ts:46) Header cells wrapped in ColumnChip; unknown columns muted Whitespace flags header with leading/trailing space → ContractAlert blocking (server does not normalize headers, 08 §1 ) Phone horizontal scroll, sticky first column (row #) a11y <table> semantics with th per column; row headers for #
Variant Colour (M3, 00-shared/02 ) Meaning
requiredprimary containermust be present; missing → blocking alert optionalsecondaryContainerrollNumber only (students-import.adapter.ts:25)unknownsurfaceVariantignored by server (parse is columns:true, unknown keys dropped — bulk-import.service.ts:26-30)
Two severities:
blocking — missing required column, whitespace-damaged header →
Next disabled; lists exact column names matching error strings
Missing required column "X". (students-import.adapter.ts:43).warning — unknown columns ignored; > 1000 rows; > 2 MB.
Renders server-exact copy where it mirrors a server rejection
(06 §2.2 ).
Hero variants (per 06 §4.1 ): all-success (✓), partial (⚠), full-failure
(✗), pre-row rejection (server 400/404).
Counts with invariant check imported + failed === totalRows
(import-adapter.interface.ts:14-25); mismatch → data-error banner.
Sub-text links to server facts: notifications fanned out per row
(event-queue-map.ts:10,28).
Columns: Row (physical line), Fields (columns implicated), Error
(full exact string, 08 §2 ), trailing actions (copy, download).
Grouping filter chips (ErrorGroupChip): Duplicates · References · Format ·
Create-time (04 §7 ).
Pagination at 50 rows (client-side; no server pagination for reports —
the report is one object, import-adapter.interface.ts:19-25).
Row tap → expand detail (mobile tile) or inline expansion (desktop);
"go to file line N" hint (row number is the file line).
Row number column pinned on horizontal scroll; zebra striping off for a11y
contrast.
Indeterminate bar + honest copy ("single request, no progress events",
bulk-import.service.ts:22-65).
Includes the timeout/partial-upload guidance (06 §4.1a ).
Seam for (planned) async: the panel accepts a progress value 0..1 and
switches to determinate when a job API exists (13 §4 ).
Entity selector (hard-coded students, students-import.adapter.ts:15),
format label CSV, roster-snapshot disclaimer (04 §6), Download CSV
button → GET /bulk/export/:entity (bulk.controller.ts:50-60).
AppButton (filled/outlined/text), AppCard, AppAlert, AppSnackbar,
AppChips, AppEmptyState, AppSkeleton, AppOfflineBanner, AppDialog
(confirm re-upload), AppMenu, AppFAB (SS5 → import), AppListTile,
AppBadge (error counts).