Document reporting interface patterns

webui/src/features/reporting/ProviderReportWorkspace.tsx

@@ -7,6 +7,7 @@ import {
   IconButton,
   MetricCard,
   StatusBadge,
+  hasScope,
   type ApiSettings,
   type AuthInfo
 } from "@govoplan/core-webui";
@@ -32,6 +33,7 @@ export function ProviderReportWorkspace({ settings, auth, report }: {
   const [running, setRunning] = useState(false);
   const [error, setError] = useState("");
   const tenant = auth.active_tenant ?? auth.tenant;
+  const canRun = hasScope(auth, "reporting:report:run");
   const audienceScope = useMemo(() => ({
     scope_type: "tenant",
     scope_id: tenant.id,
@@ -101,6 +103,15 @@ export function ProviderReportWorkspace({ settings, auth, report }: {
   const missingRequired = report.parameters.some((item) =>
     item.required && (parameters[item.key] === undefined || parameters[item.key] === "")
   );
+  const runDisabledReason = !canRun
+    ? "Report run permission is required."
+    : !report.available
+      ? report.unavailable_reason ?? "Policy does not allow this report."
+      : missingRequired
+        ? "Complete the required report parameters."
+        : !purpose.trim()
+          ? "Record the purpose for this governed report run."
+          : undefined;
   return (
     <>
       <header className="reporting-result-header">
@@ -113,7 +124,8 @@ export function ProviderReportWorkspace({ settings, auth, report }: {
           <Button
             variant="primary"
             onClick={() => void run()}
-            disabled={!report.available || running || missingRequired || !purpose.trim()}>
+            disabled={running || Boolean(runDisabledReason)}
+            disabledReason={runDisabledReason}>
             <Play size={16} aria-hidden="true" /> {running ? "Running" : "Run"}
           </Button>
         </div>