feat: split builder reordering, sliders, avatars, and invoice tags (#527)

Implements #471, #468, #469, #470 without adding dependencies — the
libraries named in the issues (@dnd-kit, @headlessui/react,
@radix-ui/react-slider, lucide-react) are not used in this repo, so
native HTML5 drag and native range inputs stand in for them.

#471 Drag handle per recipient row, HTML5 drag reordering with a
drop-zone indicator, and Up/Down arrow reordering from the focused
handle. Rows move as whole objects so percentages are never disturbed.

#468 Per-row range slider (1% steps) plus a colour-coded sum indicator
that turns green only at exactly 100%. Create Invoice is disabled with
a tooltip while the sum is invalid. An exact-value number field is kept
alongside each slider to preserve the sub-1% precision that
"Equalize Shares" produces.

#469 Gravatar (HTTPS, d=404) with a deterministic colour fallback
seeded from the address, behind a circular skeleton. MD5 is implemented
locally and verified against Node's crypto.

#470 Off-chain tag store keyed by invoice id (Invoice is an on-chain SDK
type), GET/PATCH routes, a cached useInvoiceTags hook with optimistic
writes, an ARIA combobox tag input, pills on cards and detail, and a
?tag= dashboard filter.

Co-

Co-authored-by: Emmanuel Chukwunyere <emmanuelanalaba@gmail.com>

Author: Maki-Zeninn

next.config.js

@@ -5,6 +5,17 @@ const { withSentryConfig } = require("@sentry/nextjs");
 
 /** @type {import('next').NextConfig} */
 const nextConfig = {
+  images: {
+    // Recipient avatars fall back to Gravatar; served unoptimized so no image
+    // requests are proxied through the Next.js optimizer.
+    remotePatterns: [
+      {
+        protocol: "https",
+        hostname: "www.gravatar.com",
+        pathname: "/avatar/**",
+      },
+    ],
+  },
   async headers() {
     return [
       {

src/__tests__/splitBuilderReorder.test.tsx

@@ -0,0 +1,176 @@
+/**
+ * Issue #471 — drag-to-reorder recipients in the split builder.
+ */
+import { render, screen, fireEvent } from "@testing-library/react";
+import { vi } from "vitest";
+import SplitCalculator from "@/components/SplitCalculator";
+import { moveItem } from "@/lib/reorder";
+import type { RecipientLine, SplitMeta } from "@/hooks/useSplitCalculator";
+
+vi.mock("@/lib/addressBook", () => ({
+  getEmailForAddress: () => undefined,
+}));
+
+function line(address: string, sharePercent: number): RecipientLine {
+  return { address, sharePercent, taxRatePercent: 0, fixedFeeXLM: 0 };
+}
+
+const recipients = [line("GAAA1", 50), line("GBBB2", 30), line("GCCC3", 20)];
+
+function renderBuilder(onChange?: (m: SplitMeta) => void) {
+  return render(
+    <SplitCalculator
+      splitMeta={{ totalAmount: 100, assetCode: "USDC", recipients }}
+      onSplitMetaChange={onChange}
+    />
+  );
+}
+
+/** Addresses in the order they currently appear in the DOM. */
+function renderedAddresses(): string[] {
+  return screen
+    .getAllByPlaceholderText("G...")
+    .map((el) => (el as HTMLInputElement).value);
+}
+
+/** sharePercent values in DOM order, read off the exact-value number inputs. */
+function renderedShares(): number[] {
+  return screen
+    .getAllByLabelText(/share percentage, exact value/i)
+    .map((el) => Number((el as HTMLInputElement).value));
+}
+
+describe("moveItem", () => {
+  it("moves an item forward and backward without mutating the source", () => {
+    const src = ["a", "b", "c"];
+    expect(moveItem(src, 0, 2)).toEqual(["b", "c", "a"]);
+    expect(moveItem(src, 2, 0)).toEqual(["c", "a", "b"]);
+    expect(src).toEqual(["a", "b", "c"]);
+  });
+
+  it("is a no-op for equal or out-of-range indices", () => {
+    const src = ["a", "b", "c"];
+    expect(moveItem(src, 1, 1)).toEqual(src);
+    expect(moveItem(src, -1, 1)).toEqual(src);
+    expect(moveItem(src, 0, 9)).toEqual(src);
+  });
+
+  it("preserves object identity so per-row values travel with the row", () => {
+    const a = { sharePercent: 50 };
+    const b = { sharePercent: 50 };
+    const moved = moveItem([a, b], 0, 1);
+    expect(moved[1]).toBe(a);
+  });
+});
+
+describe("SplitCalculator reordering", () => {
+  it("renders a drag handle on the leading edge of every row", () => {
+    renderBuilder();
+    expect(screen.getByTestId("drag-handle-0")).toBeInTheDocument();
+    expect(screen.getByTestId("drag-handle-1")).toBeInTheDocument();
+    expect(screen.getByTestId("drag-handle-2")).toBeInTheDocument();
+
+    // Leading edge: the handle is the row's first interactive element.
+    const row = screen.getByTestId("recipient-row-0");
+    expect(row.querySelector("button")).toBe(screen.getByTestId("drag-handle-0"));
+  });
+
+  it("reorders rows via drag and drop from the handle", () => {
+    renderBuilder();
+    expect(renderedAddresses()).toEqual(["GAAA1", "GBBB2", "GCCC3"]);
+
+    const handle = screen.getByTestId("drag-handle-0");
+    const source = screen.getByTestId("recipient-row-0");
+    const target = screen.getByTestId("recipient-row-2");
+
+    fireEvent.mouseDown(handle);
+    fireEvent.dragStart(source);
+    fireEvent.dragOver(target);
+    fireEvent.drop(target);
+
+    expect(renderedAddresses()).toEqual(["GBBB2", "GCCC3", "GAAA1"]);
+  });
+
+  it("shows a drop-zone indicator on the row being dragged over", () => {
+    renderBuilder();
+
+    fireEvent.mouseDown(screen.getByTestId("drag-handle-0"));
+    fireEvent.dragStart(screen.getByTestId("recipient-row-0"));
+    fireEvent.dragOver(screen.getByTestId("recipient-row-1"));
+
+    expect(screen.getByTestId("recipient-row-1").className).toMatch(/ring-indigo-500/);
+    // The dragged row is dimmed rather than marked as its own drop target.
+    expect(screen.getByTestId("recipient-row-0").className).toMatch(/opacity-50/);
+    expect(screen.getByTestId("recipient-row-0").className).not.toMatch(/ring-indigo-500/);
+  });
+
+  it("reorders with ArrowDown/ArrowUp once the handle has focus", () => {
+    renderBuilder();
+
+    const handle = screen.getByTestId("drag-handle-0");
+    handle.focus();
+    fireEvent.keyDown(handle, { key: "ArrowDown" });
+    expect(renderedAddresses()).toEqual(["GBBB2", "GAAA1", "GCCC3"]);
+
+    // Focus follows the moved row so repeated presses keep moving it.
+    expect(document.activeElement).toBe(screen.getByTestId("drag-handle-1"));
+
+    fireEvent.keyDown(screen.getByTestId("drag-handle-1"), { key: "ArrowUp" });
+    expect(renderedAddresses()).toEqual(["GAAA1", "GBBB2", "GCCC3"]);
+  });
+
+  it("does not move past the ends of the list", () => {
+    renderBuilder();
+
+    fireEvent.keyDown(screen.getByTestId("drag-handle-0"), { key: "ArrowUp" });
+    expect(renderedAddresses()).toEqual(["GAAA1", "GBBB2", "GCCC3"]);
+
+    fireEvent.keyDown(screen.getByTestId("drag-handle-2"), { key: "ArrowDown" });
+    expect(renderedAddresses()).toEqual(["GAAA1", "GBBB2", "GCCC3"]);
+  });
+
+  it("keeps each recipient's percentage attached to its row when reordering", () => {
+    renderBuilder();
+    expect(renderedShares()).toEqual([50, 30, 20]);
+
+    fireEvent.keyDown(screen.getByTestId("drag-handle-0"), { key: "ArrowDown" });
+
+    // The 50% row moved to position 2 — values travelled with it, and no
+    // redistribution happened.
+    expect(renderedAddresses()).toEqual(["GBBB2", "GAAA1", "GCCC3"]);
+    expect(renderedShares()).toEqual([30, 50, 20]);
+  });
+
+  it("includes the new order in the serialized split payload", () => {
+    const onChange = vi.fn();
+    renderBuilder(onChange);
+
+    fireEvent.keyDown(screen.getByTestId("drag-handle-0"), { key: "ArrowDown" });
+
+    const lastPayload = onChange.mock.calls[onChange.mock.calls.length - 1][0] as SplitMeta;
+    expect(lastPayload.recipients.map((r) => r.address)).toEqual([
+      "GBBB2",
+      "GAAA1",
+      "GCCC3",
+    ]);
+    expect(lastPayload.recipients.map((r) => r.sharePercent)).toEqual([30, 50, 20]);
+  });
+
+  it("announces keyboard moves to assistive technology", () => {
+    renderBuilder();
+    fireEvent.keyDown(screen.getByTestId("drag-handle-0"), { key: "ArrowDown" });
+    expect(
+      screen.getByText(/moved from position 1 to position 2 of 3/i)
+    ).toBeInTheDocument();
+  });
+
+  it("omits drag handles in read-only mode", () => {
+    render(
+      <SplitCalculator
+        splitMeta={{ totalAmount: 100, assetCode: "USDC", recipients }}
+        readOnly
+      />
+    );
+    expect(screen.queryByTestId("drag-handle-0")).not.toBeInTheDocument();
+  });
+});

src/__tests__/splitSlider.test.tsx

@@ -0,0 +1,126 @@
+/**
+ * Issue #468 — split ratio sliders with real-time sum validation.
+ */
+import { render, screen, fireEvent, within } from "@testing-library/react";
+import { vi } from "vitest";
+import SplitCalculator from "@/components/SplitCalculator";
+import SplitSumIndicator from "@/components/invoice/SplitSumIndicator";
+import type { RecipientLine, SplitMeta } from "@/hooks/useSplitCalculator";
+
+vi.mock("@/lib/addressBook", () => ({
+  getEmailForAddress: () => undefined,
+}));
+
+function line(address: string, sharePercent: number): RecipientLine {
+  return { address, sharePercent, taxRatePercent: 0, fixedFeeXLM: 0 };
+}
+
+function renderBuilder(recipients: RecipientLine[], onChange?: (m: SplitMeta) => void) {
+  return render(
+    <SplitCalculator
+      splitMeta={{ totalAmount: 100, assetCode: "USDC", recipients }}
+      onSplitMetaChange={onChange}
+    />
+  );
+}
+
+function sliders(): HTMLInputElement[] {
+  return screen.getAllByLabelText(
+    /^Recipient \d+ share percentage$/i
+  ) as HTMLInputElement[];
+}
+
+describe("SplitSumIndicator", () => {
+  it("turns green only at exactly 100%", () => {
+    const { rerender } = render(<SplitSumIndicator sum={100} isValid />);
+    expect(screen.getByTestId("split-sum-bar")).toHaveAttribute("data-state", "valid");
+    expect(screen.getByTestId("split-sum-bar").className).toMatch(/bg-emerald-500/);
+
+    rerender(<SplitSumIndicator sum={99.9} isValid={false} />);
+    expect(screen.getByTestId("split-sum-bar")).toHaveAttribute("data-state", "under");
+    expect(screen.getByTestId("split-sum-bar").className).toMatch(/bg-red-500/);
+
+    rerender(<SplitSumIndicator sum={120} isValid={false} />);
+    expect(screen.getByTestId("split-sum-bar")).toHaveAttribute("data-state", "over");
+    expect(screen.getByTestId("split-sum-bar").className).toMatch(/bg-red-500/);
+  });
+
+  it("reports how much is left to allocate, or the overage", () => {
+    const { rerender } = render(<SplitSumIndicator sum={70} isValid={false} />);
+    expect(screen.getByText(/30% left to allocate/i)).toBeInTheDocument();
+
+    rerender(<SplitSumIndicator sum={115} isValid={false} />);
+    expect(screen.getByText(/over-allocated by 15%/i)).toBeInTheDocument();
+  });
+
+  it("exposes progressbar semantics", () => {
+    render(<SplitSumIndicator sum={40} isValid={false} />);
+    const bar = screen.getByRole("progressbar");
+    expect(bar).toHaveAttribute("aria-valuenow", "40");
+    expect(bar).toHaveAttribute("aria-valuemin", "0");
+    expect(bar).toHaveAttribute("aria-valuemax", "100");
+  });
+});
+
+describe("SplitCalculator sliders", () => {
+  it("renders a slider per recipient row", () => {
+    renderBuilder([line("GAAA1", 60), line("GBBB2", 40)]);
+    const all = sliders();
+    expect(all).toHaveLength(2);
+    expect(all[0]).toHaveAttribute("type", "range");
+    expect(all[0]).toHaveValue("60");
+    expect(all[1]).toHaveValue("40");
+  });
+
+  it("updates that recipient's percentage in real time", () => {
+    renderBuilder([line("GAAA1", 60), line("GBBB2", 40)]);
+
+    fireEvent.change(sliders()[0], { target: { value: "75" } });
+
+    expect(sliders()[0]).toHaveValue("75");
+    const indicator = screen.getByTestId("split-sum-indicator");
+    expect(within(indicator).getByText("115% / 100%")).toBeInTheDocument();
+  });
+
+  it("does not redistribute the remainder to other recipients", () => {
+    renderBuilder([line("GAAA1", 50), line("GBBB2", 30), line("GCCC3", 20)]);
+
+    fireEvent.change(sliders()[0], { target: { value: "10" } });
+
+    // Only the adjusted row changes; the other two keep their values even
+    // though the split is now under-allocated.
+    expect(sliders().map((s) => s.value)).toEqual(["10", "30", "20"]);
+  });
+
+  it("steps by 1% so arrow keys give whole-percent increments", () => {
+    renderBuilder([line("GAAA1", 100)]);
+    expect(sliders()[0]).toHaveAttribute("step", "1");
+    expect(sliders()[0]).toHaveAttribute("min", "0");
+    expect(sliders()[0]).toHaveAttribute("max", "100");
+  });
+
+  it("keeps a paired exact-value field for sub-1% precision", () => {
+    renderBuilder([line("GAAA1", 33.3333), line("GBBB2", 66.6667)]);
+
+    const exact = screen.getAllByLabelText(
+      /share percentage, exact value/i
+    ) as HTMLInputElement[];
+    expect(exact[0]).toHaveValue(33.3333);
+
+    fireEvent.change(exact[0], { target: { value: "33.5" } });
+    expect(exact[0]).toHaveValue(33.5);
+  });
+
+  it("marks the split valid only when the shares total exactly 100", () => {
+    const onChange = vi.fn();
+    renderBuilder([line("GAAA1", 50), line("GBBB2", 50)], onChange);
+
+    expect(screen.getByTestId("split-sum-bar")).toHaveAttribute("data-state", "valid");
+
+    fireEvent.change(sliders()[0], { target: { value: "51" } });
+    expect(screen.getByTestId("split-sum-bar")).toHaveAttribute("data-state", "over");
+    expect(
+      screen.getByText(/share percentages must sum to 100%/i)
+    ).toBeInTheDocument();
+  });
+});

src/app/api/invoices/[id]/tags/route.ts

@@ -0,0 +1,69 @@
+import { NextRequest, NextResponse } from "next/server";
+import {
+  MAX_TAGS_PER_INVOICE,
+  TagsPayloadSchema,
+  getTags,
+  setTags,
+} from "@/lib/invoiceTags";
+
+/** GET /api/invoices/:id/tags — tags currently applied to one invoice. */
+export async function GET(
+  _request: NextRequest,
+  { params }: { params: { id: string } }
+) {
+  try {
+    return NextResponse.json(
+      { invoiceId: params.id, tags: getTags(params.id) },
+      { status: 200 }
+    );
+  } catch (error) {
+    console.error("Tag fetch error:", error);
+    return NextResponse.json(
+      {
+        error: "Failed to fetch tags",
+        details: error instanceof Error ? error.message : String(error),
+      },
+      { status: 500 }
+    );
+  }
+}
+
+/**
+ * PATCH /api/invoices/:id/tags — replace the invoice's tag set.
+ *
+ * The client sends the full desired list (both adds and removes go through
+ * here), which keeps optimistic UI updates trivial to reconcile: the response
+ * is the authoritative normalized set.
+ */
+export async function PATCH(
+  request: NextRequest,
+  { params }: { params: { id: string } }
+) {
+  try {
+    const rawBody = await request.json();
+    const parsed = TagsPayloadSchema.safeParse(rawBody);
+
+    if (!parsed.success) {
+      return NextResponse.json(
+        {
+          error: `Invalid tags payload — expected { tags: string[] } with at most ${MAX_TAGS_PER_INVOICE} entries`,
+          details: parsed.error.issues,
+        },
+        { status: 422 }
+      );
+    }
+
+    const tags = setTags(params.id, parsed.data.tags);
+
+    return NextResponse.json({ success: true, invoiceId: params.id, tags }, { status: 200 });
+  } catch (error) {
+    console.error("Tag save error:", error);
+    return NextResponse.json(
+      {
+        error: "Failed to persist tags",
+        details: error instanceof Error ? error.message : String(error),
+      },
+      { status: 500 }
+    );
+  }
+}