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>

webui/src/features/reporting/ReportingPage.tsx

@@ -21,6 +21,7 @@ import {
   Button,
   DataGrid,
   Dialog,
+  DocumentationHelpLink,
   DismissibleAlert,
   IconButton,
   LoadingIndicator,
@@ -202,6 +203,10 @@ export default function ReportingPage({ settings, auth }: PlatformRouteContext)
             />
           </form>
           <span className="reporting-count">{reports.length + providerReports.length} reports</span>
+          <DocumentationHelpLink
+            reference={{ topicId: "reporting.governed-bi", documentationType: "user" }}
+            label="Open reporting documentation"
+          />
           <IconButton
             label="Reload reports"
             icon={<RefreshCw size={17} />}
@@ -265,7 +270,11 @@ export default function ReportingPage({ settings, auth }: PlatformRouteContext)
                       <IconButton label="Schedule report" icon={<CalendarClock size={17} />} variant="ghost" onClick={() => setScheduleDialogOpen(true)} />
                     }
                     <IconButton label="Save current view" icon={<Save size={17} />} variant="ghost" onClick={() => setSaveDialogOpen(true)} />
-                    <Button variant="primary" onClick={() => void execute()} disabled={!canRun || running}>
+                    <Button
+                      variant="primary"
+                      onClick={() => void execute()}
+                      disabled={!canRun || running}
+                      disabledReason={!canRun ? "Report run permission is required." : undefined}>
                       <Play size={16} aria-hidden="true" /> {running ? "Running" : "Run"}
                     </Button>
                   </div>