Files
PaperClipAI/ui/src/components/BudgetPolicyCard.tsx
T
Evyatar BluzerandAndrew Aymeloglu 1791979512 refactor(a11y): add ARIA progressbar attributes to BudgetPolicyCard (#1805)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Humans oversee those agents in teams, so each team needs its own
spend controls
> - The BudgetPolicyCard component shows how much of a budget is
consumed
> - The utilization bar in that card is a styled div with no ARIA role,
value, or label
> - A screen reader user therefore cannot hear how much budget is used
> - This pull request adds role="progressbar" and the matching ARIA
value attributes
> - The benefit is that assistive technology announces budget
utilization the same way sighted users see it

## Linked Issues or Issue Description

No existing issue. Related pull requests: #1869 and #1878 add the same
progressbar
semantics to ProviderQuotaCard and QuotaBar. They touch different files.

The problem follows the bug report template:

**What happened?**
The budget utilization bar in `BudgetPolicyCard` renders as a plain
`div`. It has no
`role`, no `aria-valuenow`, and no accessible name. A screen reader
announces nothing
for it. The user can read the "Remaining" amount, but not the
utilization percentage.

**Expected behavior**
The bar is announced as a progress bar. It reports the current
utilization percentage,
with its minimum and maximum.

**Steps to reproduce**
1. Open a project or agent page that shows the budget card.
2. Start VoiceOver (Cmd+F5 on macOS).
3. Move the cursor to the budget utilization bar.
4. VoiceOver announces nothing.

**Paperclip version or commit**
master, `ui/src/components/BudgetPolicyCard.tsx`.

**Deployment mode**
Local dev (pnpm dev).

## What Changed

- Added `role="progressbar"` to the inner bar element.
- Added `aria-valuenow` with the rounded utilization percentage.
- Added `aria-valuemin={0}` and `aria-valuemax={100}`.
- Added `aria-label` in the form `Budget utilization: 73% used`.

`aria-valuenow` and `aria-label` use the same `progress` value. That
value is already
capped at 100 by `Math.min(100, summary.utilizationPercent)`, so the
reported value
stays inside the min/max range when a scope is over budget.

An earlier revision also changed the budget amount `Input` to
`type="number"`. That
change is removed. It changed input behavior and was not an
accessibility fix.
See "Risks".

## Verification

1. Open a page that shows the budget card.
2. Start VoiceOver (Cmd+F5 on macOS) and move to the utilization bar.
3. VoiceOver announces "Budget utilization: X% used, progress
indicator".
4. Inspect the element. `aria-valuenow` equals the displayed percentage,
and it stays
   at 100 when utilization is above 100%.

The change adds attributes only. There is no visual change.

## Risks

Low risk. The change adds ARIA attributes to one element in one
component. It changes
no logic, no styling, and no layout.

The `type="number"` change is removed on purpose. With `type="number"`,
a browser
reports an empty string for text it cannot parse. `parseDollarInput("")`
then returns
`0` instead of `null`, so the existing "Enter a valid non-negative
dollar amount."
error never appears and unparseable input silently becomes a $0.00
budget. The
`inputMode="decimal"` input keeps that validation path working.

## Model Used

Original implementation by @bluzername. The author did not state a
model.
Scope reduction, branch update, and this description: Claude Opus 5 (1M
context,
extended thinking, tool use), prepared under maintainer review.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have described the issue in-PR following the relevant issue
template
- [x] I have not referenced internal/instance-local Paperclip issues or
links
- [x] My branch name describes the change
- [x] I have considered and documented any risks above
- [ ] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [ ] I have run tests locally and they pass
- [ ] I have added or updated tests where applicable
- [ ] I have updated relevant documentation to reflect my changes
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Andrew Aymeloglu <aaymeloglu@gmail.com>
2026-08-07 19:51:03 -05:00

225 lines
9.5 KiB
TypeScript

import { useEffect, useState } from "react";
import type { BudgetPolicySummary } from "@paperclipai/shared";
import { AlertTriangle, PauseCircle, ShieldAlert, Wallet } from "lucide-react";
import { cn, formatCents } from "../lib/utils";
import { Button } from "@/components/ui/button";
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
import { Input } from "@/components/ui/input";
function centsInputValue(value: number) {
return (value / 100).toFixed(2);
}
function parseDollarInput(value: string) {
const normalized = value.trim();
if (normalized.length === 0) return 0;
const parsed = Number(normalized);
if (!Number.isFinite(parsed) || parsed < 0) return null;
return Math.round(parsed * 100);
}
function windowLabel(windowKind: BudgetPolicySummary["windowKind"]) {
return windowKind === "lifetime" ? "Lifetime budget" : "Monthly UTC budget";
}
function statusTone(status: BudgetPolicySummary["status"]) {
if (status === "hard_stop") return "text-red-700 dark:text-red-300 border-red-500/30 bg-red-500/10";
if (status === "warning") return "text-amber-700 dark:text-amber-200 border-amber-500/30 bg-amber-500/10";
return "text-emerald-700 dark:text-emerald-200 border-emerald-500/30 bg-emerald-500/10";
}
export function BudgetPolicyCard({
summary,
onSave,
isSaving,
compact = false,
variant = "card",
}: {
summary: BudgetPolicySummary;
onSave?: (amountCents: number) => void;
isSaving?: boolean;
compact?: boolean;
variant?: "card" | "plain";
}) {
const [draftBudget, setDraftBudget] = useState(centsInputValue(summary.amount));
useEffect(() => {
setDraftBudget(centsInputValue(summary.amount));
}, [summary.amount]);
const parsedDraft = parseDollarInput(draftBudget);
const canSave = typeof parsedDraft === "number" && parsedDraft !== summary.amount && Boolean(onSave);
const progress = summary.amount > 0 ? Math.min(100, summary.utilizationPercent) : 0;
const StatusIcon = summary.status === "hard_stop" ? ShieldAlert : summary.status === "warning" ? AlertTriangle : Wallet;
const isPlain = variant === "plain";
const observedBudgetGrid = isPlain ? (
<div className="grid gap-6 sm:grid-cols-2">
<div>
<div className="text-(length:--text-micro) uppercase tracking-(--tracking-caps) text-muted-foreground">Observed</div>
<div className="mt-2 text-xl font-semibold tabular-nums">{formatCents(summary.observedAmount)}</div>
<div className="mt-1 text-xs text-muted-foreground">
{summary.amount > 0 ? `${summary.utilizationPercent}% of limit` : "No cap configured"}
</div>
</div>
<div>
<div className="text-(length:--text-micro) uppercase tracking-(--tracking-caps) text-muted-foreground">Budget</div>
<div className="mt-2 text-xl font-semibold tabular-nums">
{summary.amount > 0 ? formatCents(summary.amount) : "Disabled"}
</div>
<div className="mt-1 text-xs text-muted-foreground">
Soft alert at {summary.warnPercent}%{summary.paused && summary.pauseReason ? ` · ${summary.pauseReason} pause` : ""}
</div>
</div>
</div>
) : (
<div className="grid gap-3 sm:grid-cols-2">
<div className="rounded-xl border border-border/70 bg-black/[0.18] px-4 py-3">
<div className="text-(length:--text-micro) uppercase tracking-(--tracking-caps) text-muted-foreground">Observed</div>
<div className="mt-2 text-xl font-semibold tabular-nums">{formatCents(summary.observedAmount)}</div>
<div className="mt-1 text-xs text-muted-foreground">
{summary.amount > 0 ? `${summary.utilizationPercent}% of limit` : "No cap configured"}
</div>
</div>
<div className="rounded-xl border border-border/70 bg-black/[0.18] px-4 py-3">
<div className="text-(length:--text-micro) uppercase tracking-(--tracking-caps) text-muted-foreground">Budget</div>
<div className="mt-2 text-xl font-semibold tabular-nums">
{summary.amount > 0 ? formatCents(summary.amount) : "Disabled"}
</div>
<div className="mt-1 text-xs text-muted-foreground">
Soft alert at {summary.warnPercent}%{summary.paused && summary.pauseReason ? ` · ${summary.pauseReason} pause` : ""}
</div>
</div>
</div>
);
const progressSection = (
<div className="space-y-2">
<div className="flex items-center justify-between text-xs text-muted-foreground">
<span>Remaining</span>
<span>{summary.amount > 0 ? formatCents(summary.remainingAmount) : "Unlimited"}</span>
</div>
<div className={cn("h-2 overflow-hidden rounded-full", isPlain ? "bg-border/70" : "bg-muted/70")}>
<div
role="progressbar"
aria-valuenow={Math.round(progress)}
aria-valuemin={0}
aria-valuemax={100}
aria-label={`Budget utilization: ${Math.round(progress)}% used`}
className={cn(
"h-full rounded-full transition-(--tp-width-background-color) duration-200",
summary.status === "hard_stop"
? "bg-(--status-task-blocked)"
: summary.status === "warning"
? "bg-(--status-task-todo)"
: "bg-(--status-task-done)",
)}
style={{ width: `${progress}%` }}
/>
</div>
</div>
);
const pausedPane = summary.paused ? (
<div className="flex items-start gap-2 rounded-xl border border-red-500/30 bg-red-500/10 px-3 py-2 text-sm text-red-900 dark:text-red-100">
<PauseCircle className="mt-0.5 h-4 w-4 shrink-0" />
<div>
{summary.scopeType === "project"
? "Execution is paused for this project until the budget is raised or the incident is dismissed."
: "Heartbeats are paused for this scope until the budget is raised or the incident is dismissed."}
</div>
</div>
) : null;
const saveSection = onSave ? (
<div className={cn("flex flex-col gap-3 sm:flex-row sm:items-end", isPlain ? "" : "rounded-xl border border-border/70 bg-background/50 p-3")}>
<div className="min-w-0 flex-1">
<label className="text-(length:--text-micro) uppercase tracking-(--tracking-caps) text-muted-foreground">
Budget (USD)
</label>
<Input
value={draftBudget}
onChange={(event) => setDraftBudget(event.target.value)}
className="mt-2"
inputMode="decimal"
placeholder="0.00"
/>
</div>
<Button
onClick={() => {
if (typeof parsedDraft === "number" && onSave) onSave(parsedDraft);
}}
disabled={!canSave || isSaving || parsedDraft === null}
>
{isSaving ? "Saving..." : summary.amount > 0 ? "Update budget" : "Set budget"}
</Button>
</div>
) : null;
if (isPlain) {
return (
<div className="space-y-6">
<div className="flex items-start justify-between gap-6">
<div>
<div className="text-(length:--text-micro) uppercase tracking-(--tracking-caps) text-muted-foreground">
{summary.scopeType}
</div>
<div className="mt-2 text-xl font-semibold">{summary.scopeName}</div>
<div className="mt-2 text-sm text-muted-foreground">{windowLabel(summary.windowKind)}</div>
</div>
<div
className={cn(
"inline-flex items-center gap-2 text-(length:--text-micro) uppercase tracking-(--tracking-caps)",
summary.status === "hard_stop"
? "text-red-700 dark:text-red-300"
: summary.status === "warning"
? "text-amber-800 dark:text-amber-200"
: "text-muted-foreground",
)}
>
<StatusIcon className="h-3.5 w-3.5" />
{summary.paused ? "Paused" : summary.status === "warning" ? "Warning" : summary.status === "hard_stop" ? "Hard stop" : "Healthy"}
</div>
</div>
{observedBudgetGrid}
{progressSection}
{pausedPane}
{saveSection}
{parsedDraft === null ? (
<p className="text-xs text-destructive">Enter a valid non-negative dollar amount.</p>
) : null}
</div>
);
}
return (
<Card className={cn("overflow-hidden border-border/70 bg-card/80", compact ? "" : "shadow-(--shadow-extract-2)")}>
<CardHeader className={cn("gap-3", compact ? "px-4 pt-4 pb-2" : "px-5 pt-5 pb-3")}>
<div className="flex items-start justify-between gap-3">
<div>
<div className="text-(length:--text-micro) uppercase tracking-(--tracking-caps) text-muted-foreground">
{summary.scopeType}
</div>
<CardTitle className="mt-1 text-base">{summary.scopeName}</CardTitle>
<CardDescription className="mt-1">{windowLabel(summary.windowKind)}</CardDescription>
</div>
<div className={cn("inline-flex items-center gap-2 rounded-full border px-3 py-1 text-(length:--text-micro) uppercase tracking-(--tracking-caps)", statusTone(summary.status))}>
<StatusIcon className="h-3.5 w-3.5" />
{summary.paused ? "Paused" : summary.status === "warning" ? "Warning" : summary.status === "hard_stop" ? "Hard stop" : "Healthy"}
</div>
</div>
</CardHeader>
<CardContent className={cn("space-y-4", compact ? "px-4 pb-4 pt-0" : "px-5 pb-5 pt-0")}>
{observedBudgetGrid}
{progressSection}
{pausedPane}
{saveSection}
{parsedDraft === null ? (
<p className="text-xs text-destructive">Enter a valid non-negative dollar amount.</p>
) : null}
</CardContent>
</Card>
);
}