# Compact DN Row + Order Age Badge — Design

## Purpose

Two small, independent rendering improvements for two pages the
operator uses every day:

1. **`/deliveries`** — each delivery-note row currently renders only
   `DN {number}` + a one-line subline (delivery date or PO ref). The
   operator can't tell *who* a delivery note is for or whether the
   signed copy is back without scrolling up to the customer/order
   group header. This spec adds a compact subline with customer name,
   company, parent order number, and a signed-copy indicator — all
   data the service already returns, no new queries.

2. **`/orders`** — the order card subtitle already shows
   `{formatDate(order.created)}` but as a bare date string. The
   operator wants to triage by **age** ("how long has this been on my
   board") at a glance, not parse dates. This spec adds a colour-coded
   age badge (`today`, `3d old`, `7d old`, etc.) replacing the bare
   date string in the right-aligned metadata slot.

Both features share no code; they're bundled in one spec only because
they were brainstormed together.

## Scope decisions (confirmed during brainstorming)

- **DN row enrichment** — compact option from the brainstorm:
  customer name, company name, parent order number, signed-copy
  indicator. No item count, no total value (those would require a
  server-side aggregate; rejected for now).
- **Age surfacing** — colour-coded badge, not auto-sort, not
  raw-age-only. Replaces the existing date string; date is dropped
  because the badge text already conveys the date implicitly ("3d old
  on 2026-08-29" is redundant).
- **Age thresholds** — `<24h → today (green)`, `1–2d → green`,
  `3–7d → amber`, `8–14d → orange`, `>14d → red`. Tunable later.
- **No server changes** — both features consume data already
  returned by `/api/v1/deliveries` and `/api/v1/orders` (or, in
  `/orders`'s case, the page-level fetcher).
- **No PB schema changes** — purely UI/rendering work.

## Architecture

**New files:**
```
src/lib/order-age.ts            — pure age math + bucket → tailwind class
src/lib/order-age.test.ts       — unit tests for the util
```

**Modified files:**
```
src/app/(app)/deliveries/page.tsx   — DeliveryNoteRowComponent only
src/app/(app)/orders/page.tsx       — order card right-aligned metadata slot
```

No service-layer or `/api/v1` route changes. No MCP tool changes.

---

## Feature 1: Compact info on delivery-note rows

### File: `src/app/(app)/deliveries/page.tsx`

Scope: **only** the `DeliveryNoteRowComponent` function (lines
~1475-1588). No change to the grouping logic, the search filter, the
loading endpoint, or any other component on the page.

### Target row rendering

```
DN DN26083101
Acme Mining (Pty) Ltd · Master Drilling Co · ORD-2026-08-058 · 📎 signed copy
[status badge]  [Mark loaded]  [Signed copy]
```

The existing `<p>` subline at line 1537-1547 is replaced with a new
piece list:

1. **Customer name** — `dn.order?.customer_name` ?? `"Counter pickup"`.
   Always rendered (counter-pickup is the explicit no-order case).
2. **Company name** — `dn.order?.company_name`. Hidden if falsy.
3. **Order number** — `dn.order?.order_number`. Hidden if falsy.
4. **Signed-copy indicator** — `<Paperclip />` icon + `"signed copy"`
   text. Hidden if `!dn.signed_copy || dn.signed_copy.length === 0`.
   The whole indicator carries `title={dn.signed_copy.join(", ")}` so
   the operator can see the filenames on hover.

Joined by `·` (same separator convention as the order card subtitle),
in `text-muted-foreground` (matches the existing subline colour).

### Edge cases

- **Counter-pickup DN** (`dn.order === null`): customer/company/order
  pieces all collapse to a single `"Counter pickup"` label (no
  separator emitted for the missing pieces). Signed-copy indicator
  still appears if files were uploaded directly to the DN.
- **Long customer names**: the customer name piece carries
  `truncate max-w-[40ch]` + `title` to preserve hover-access. Other
  pieces are short and don't need truncation.
- **Multi-DN under one order**: each DN row still renders its own
  compact subline. The group header (customer → order → list of rows)
  is unchanged.

### Acceptance

- A DN with order attached shows: `DN {n}`, customer name, company
  name, order number, paperclip if signed copy uploaded.
- A counter-pickup DN shows: `DN {n}`, `Counter pickup`, paperclip if
  signed copy uploaded.
- A DN with no signed copy shows no paperclip.
- The page's existing search, grouping, and tab logic are unaffected.
- No new network request is made when rendering a DN row.

---

## Feature 2: Order age badge

### New file: `src/lib/order-age.ts`

```typescript
export type OrderAgeBucket = "fresh" | "recent" | "slipping" | "stale";

export interface OrderAge {
  /** Integer calendar-day delta. 0 means "today". Never negative. */
  daysOld: number;
  bucket: OrderAgeBucket;
  /** Human-readable badge label. */
  label: string;
}

/**
 * Compute the age of an order relative to `now` (defaults to
 * `new Date()`). The `daysOld` value is a **calendar-day** delta in
 * the office's local timezone (Africa/Johannesburg, hardcoded for
 * now) — an order created at 23:00 yesterday read at 01:00 today is
 * `daysOld = 0` ("today"), not 1. The day delta is computed as
 * `floor((localEndOfDay - localStartOfCreatedDay) / 1 day)` and is
 * always returned as a non-negative integer.
 *
 * Future-dated `created` values (clock skew, bad data) clamp to 0
 * to avoid showing "−1d old" or similar nonsense.
 *
 * Implementation note: use `Intl.DateTimeFormat` with the
 * Africa/Johannesburg timezone to get the local YYYY-MM-DD for both
 * dates, then subtract. Don't divide millisecond deltas by
 * 86_400_000 — that fails across DST boundaries (SA doesn't observe
 * DST but the pattern is fragile).
 */
export function getOrderAge(
  created: string | Date,
  now?: Date,
): OrderAge;

/**
 * Map an age bucket to a tailwind className for the badge.
 * Centralised so a future palette tweak is a one-line change.
 */
export function bucketToBadgeClass(bucket: OrderAgeBucket): string;
```

**Bucket thresholds:**

| `daysOld` | bucket | label |
|-----------|--------|-------|
| 0         | `fresh`  | `today` |
| 1–2       | `fresh`  | `{daysOld}d old` |
| 3–7       | `recent` | `{daysOld}d old` |
| 8–14      | `slipping` | `{daysOld}d old` |
| ≥ 15      | `stale`  | `{daysOld}d old` |

**Badge class names** (initial palette, tunable):
- `fresh` → `bg-emerald-100 text-emerald-800 dark:bg-emerald-950 dark:text-emerald-300`
- `recent` → `bg-amber-100 text-amber-800 dark:bg-amber-950 dark:text-amber-300`
- `slipping` → `bg-orange-100 text-orange-800 dark:bg-orange-950 dark:text-orange-300`
- `stale` → `bg-red-100 text-red-800 dark:bg-red-950 dark:text-red-300`

### New file: `src/lib/order-age.test.ts`

Unit tests, all pure-function:
- `daysOld = 0` (created today) → `fresh`, label `"today"`
- `daysOld = 1, 2` → `fresh`, label `"1d old"`, `"2d old"`
- `daysOld = 3, 7` → `recent`, label `"3d old"`, `"7d old"`
- `daysOld = 8, 14` → `slipping`, label `"8d old"`, `"14d old"`
- `daysOld = 15, 30, 365` → `stale`, label `"15d old"`, `"30d old"`,
  `"365d old"`
- `daysOld = -1` (future date) → clamps to `fresh`, label `"today"`
- **Local-timezone edge case**: an order created at 23:00 JNB yesterday
  read at 01:00 JNB today must return `daysOld = 0` (calendar-day delta,
  not millisecond delta). Test this with `now` injected explicitly.
- All four `bucketToBadgeClass` outputs return non-empty strings
- `bucketToBadgeClass` is stable (same input → same output)

No React rendering tests for the badge — that would be a separate
playwright/e2e concern and is out of scope.

### Modified file: `src/app/(app)/orders/page.tsx`

Scope: the right-aligned metadata line in the order card (current line
~865-867). The exact JSX currently is:

```tsx
<span className="ml-auto text-xs text-muted-foreground hidden sm:inline">
  {formatDate(order.created)}
</span>
```

Replace with:

```tsx
<OrderAgeBadge created={order.created} className="ml-auto hidden sm:inline-flex" />
```

Where `OrderAgeBadge` is a tiny new inline component in the same
file (kept local — used only here for now; if a second page needs it,
it can be hoisted to `src/components/order-age-badge.tsx`):

```tsx
function OrderAgeBadge({
  created,
  className,
}: {
  created: string;
  className?: string;
}) {
  const age = getOrderAge(created);
  return (
    <span
      className={cn(
        "rounded-full px-2 py-0.5 text-[10px] font-medium tabular-nums",
        bucketToBadgeClass(age.bucket),
        className,
      )}
      title={`Created ${formatDate(created)}`}
    >
      {age.label}
    </span>
  );
}
```

The `title=` attribute preserves the absolute date for operators who
want to know the exact day — addresses the brainstorm's "drop raw
date" option concern without keeping it as primary UI.

The existing `formatDate` import (currently from
`@/lib/pb-helpers`, line ~1596 — `formatDate(dateStr: string)`) is
kept on the page. `getOrderAge` itself does **not** import
`formatDate`; it returns the age label only.

### Edge cases

- **Sorting**: not changing. The badge surfaces age; the operator
  still sorts by `created` if they want.
- **Rep filtering**: the recent commit
  `feat(invoicing): filter rows to the logged-in rep's own orders` is
  orthogonal. Age badge fires regardless of who the rep is.
- **Long lists**: each card gets one badge. No batched summary view
  changes.
- **Existing `formatDate` call**: `formatDate(order.created)` moves
  from the JSX into the badge's `title=` tooltip so the absolute
  date is still accessible on hover.

### Acceptance

- An order created today shows a green `today` badge in the
  right-aligned slot where the date used to live.
- An order 5 days old shows an amber `5d old` badge.
- An order 20 days old shows a red `20d old` badge.
- Hovering the badge reveals the full `Created YYYY-MM-DD` tooltip.
- The order card layout is otherwise unchanged — the badge slot has
  the same `ml-auto hidden sm:inline` styling hooks.

---

## What's NOT in scope

- **No new server endpoints.** Both features use existing data.
- **No PB schema changes.** Purely UI.
- **No item count / total value on DN rows.** Rejected during
  brainstorm (would need a server-side aggregate).
- **No sorting changes on /orders.** Badge only.
- **No changes to MCP tools.**
- **No changes to /api/v1 routes.**
- **No changes to other delivery-note pages** (`/delivery-notes`,
  `/delivery-notes/[id]`, `/delivery-note-print`). Only
  `/deliveries`'s row component.

## Testing

- `src/lib/order-age.test.ts` — 6+ unit tests covering all bucket
  thresholds + future-date clamp + `bucketToBadgeClass` stability.
- Manual smoke: open `/orders`, verify badges appear with correct
  colours for orders of various ages; open `/deliveries`, verify the
  DN row subline shows customer/company/order/paperclip as expected.
- Existing page tests (if any) for `/orders` and `/deliveries`
  should continue to pass — no layout regressions.

## Risk assessment

**Low.** Both features are additive rendering changes against
existing, well-typed payloads. The age util is a pure function and
the only file with logic worth testing. The DN row change touches
one component and doesn't change any user-facing interaction
(no new buttons, no new fields).