Multi-Document Upload with Split-Button Indicator

Date: 2026-03-09 Status: Approved Prototype: tmp-ui-sandbox/approach-A/button-indicator-v3.html

Problem

When users upload multiple documents of mixed types (invoices, contracts, notices), the current UI:

1. Adds all files as "Processing" rows to the current page's table, even before classification determines their type
2. Provides no feedback during upload + classification (empty 200 response for multi-file)
3. Documents routed to other pages after classification just "disappear" without explanation

Design

Split Upload Button

The existing Upload button becomes a split button with two zones:

• Left: Upload action — always visible, always clickable. Blue Upload button with upload icon. Clicking opens the file picker. Works identically whether idle or mid-batch.
• Right: Status indicator — appears only when files are processing. Shows a spinner + badge with remaining file count. Clicking toggles the popover. Auto-hides ~5 seconds after all files complete.

When idle, only the left side is visible (looks identical to the current Upload button). The right side slides in when a batch starts.

Popover

Anchored below the split button, right-aligned. Opens automatically on upload, toggleable via the status indicator.

Structure:

• Header: "Processing files..." / "All uploads complete" + close button
• Body: scrollable list of file items, grouped by batch
• Footer: summary line ("3 completed, 1 discarded")

Batch separators appear when multiple uploads overlap (e.g., "Batch 1 — 11:42"). Newest batch prepends at the top.

Each file item is an <a> element linking to /documents/view/{id}:

• Icon: color-coded by current phase (blue=uploading, amber=classifying, purple=processing, green=completed, red=failed, gray=skipped)
• Filename
• Status line: "Uploading..." / "Classifying..." / "Extracting & validating..." / "Completed" / "Failed" / "Discarded"
• Type tag: fades in after classification — colored badge showing "Invoice", "Contract", "Financial Notice", etc.
• Activity bar: indeterminate sliding animation, color matches phase. Fades out on completion. No server-side progress tracking needed.

Terminal states:

• Completed (green): clickable, links to document
• Failed (red): dimmed, not clickable
• Discarded (gray, 50% opacity): for "other" type docs that are thrown away, not clickable

Behavior

• Unified single/multi-file: no redirect for single files. Always uses the popover flow. Single file items are clickable to navigate to the document.
• Append on second upload: clicking Upload while a batch is processing starts a new batch. New files prepend to the popover with batch separator. Badge count increases.
• Navigation loses state: if the user navigates away mid-processing, the popover state is lost. Files continue processing server-side and appear via SSE.
• Auto-cleanup: status indicator auto-hides ~5 seconds after all files complete (if popover is closed).

Table Row Animation

When a document completes and belongs on the current page, a new row appears at the top of the table with a slide-in animation: translateY(-8px) + opacity 0→1, 0.3s ease-out. This animation applies to:

• Rows inserted by the upload popover flow
• Rows arriving via SSE (existing real-time updates, currently no animation)

Backend Changes Required (HTMX-Idiomatic Revision)

1. Upload endpoint response: Returns server-rendered HTML popover items (not JSON). The form uses hx-post with hx-swap="afterbegin" targeting #popover-body. Each file item is an <a> element with id="pop-file-{uuid}" and href="/documents/view/{uuid}". Skipped (duplicate) files are rendered as terminal state immediately.

2. SSE events: No new event type needed. The existing new-document event carries HTML with multiple hx-swap-oob elements. HTMX processes all OOB elements automatically from a single event. Each event can include:

   • An OOB popover item update (hx-swap-oob="outerHTML" targeting #pop-file-{id}) — silently no-ops if no matching element exists (e.g., email-ingested documents)
   • A table row — either as primary content (afterbegin into tbody for new rows) or OOB (hx-swap-oob="true" for in-place updates)

3. No table row until completion: In-progress events are skipped (no DB query, no table row). Table rows only appear when ingestion completes AND the document type matches the current page. This fixes the "ghost row" problem where documents appeared on wrong-type pages.

4. No SSE looper changes: The exec-fn continues returning a single {:event :data} map. The :data string simply contains concatenated HTML with OOB attributes — HTMX handles the rest.

What Doesn't Change

• Upload button placement (stays in page header on AP and Document Management)
• File input mechanics (same <input multiple>, same max 5 limit, HTMX hx-encoding="multipart/form-data")
• Backend ingestion pipeline (same S3 upload, SQS queue, worker processing)
• Document Management page gets the same split-button treatment as AP
• SSE looper infrastructure (sse.clj)

CSS Additions

New styles needed in style.css:

• .split-btn, .split-btn-upload, .split-btn-status — split button layout
• .upload-popover, .popover-header, .popover-body, .popover-summary — popover structure
• .pop-file, .pop-file-icon, .pop-file-info, .pop-file-type — file items
• .pop-activity, .pop-activity-bar — indeterminate activity animation
• .batch-separator — batch grouping in popover
• .row-new with row-slide-in keyframes — table row entrance animation
• .popover-backdrop — click-outside dismissal

JS Additions

Minimal client-side state module (upload.js). The DOM is the source of truth:

• onUploadResponse() — called via hx-on::after-request after upload; shows status indicator, opens popover
• onItemLoad() — called via hx-on::load when SSE replaces a popover item; recounts badge, updates summary
• updateBadge() — queries #popover-body .pop-file.processing count
• updateSummary() — queries completed/failed/skipped counts
• togglePopover() / openPopover() / closePopover() — visibility toggles
• Auto-hide status indicator ~5s after all files complete