From d11b74fd857a6ebf47658b707605a64a10be764f Mon Sep 17 00:00:00 2001
From: Oliver <oliver.henry.walters@gmail.com>
Date: Fri, 23 Oct 2026 11:30:34 +1100
Subject: [PATCH] [UI] Badge tooltips (#13074)

Add explanatory tooltips to detail page badges
---
 .../src/components/details/DetailsBadge.tsx      | 16 ++++++++++++----
 src/frontend/src/pages/build/BuildDetail.tsx     |  1 +
 src/frontend/src/pages/company/CompanyDetail.tsx |  1 +
 .../src/pages/company/SupplierPartDetail.tsx     |  4 ++++
 src/frontend/src/pages/part/PartDetail.tsx       | 11 +++++++++++
 .../src/pages/sales/SalesOrderShipmentDetail.tsx |  5 +++++
 src/frontend/src/pages/stock/StockDetail.tsx     |  8 ++++++++
 7 files changed, 42 insertions(+), 4 deletions(-)

diff --git a/src/frontend/src/components/details/DetailsBadge.tsx b/src/frontend/src/components/details/DetailsBadge.tsx
index 93f60fd5e3..6d91d6a40f 100644
--- a/src/frontend/src/components/details/DetailsBadge.tsx
+++ b/src/frontend/src/components/details/DetailsBadge.tsx
@@ -1,10 +1,11 @@
-import { Badge } from '@mantine/core';
+import { Badge, Tooltip } from '@mantine/core';
 
 export type DetailsBadgeProps = {
   color: string;
   label: string;
   size?: string;
   visible?: boolean;
+  tooltip?: string;
 };
 
 export default function DetailsBadge(props: Readonly<DetailsBadgeProps>) {
@@ -13,8 +14,15 @@ export default function DetailsBadge(props: Readonly<DetailsBadgeProps>) {
   }
 
   return (
-    <Badge color={props.color} variant='filled' size={props.size ?? 'lg'}>
-      {props.label}
-    </Badge>
+    <Tooltip
+      label={props.tooltip}
+      disabled={!props.tooltip}
+      position='bottom'
+      withArrow
+    >
+      <Badge color={props.color} variant='filled' size={props.size ?? 'lg'}>
+        {props.label}
+      </Badge>
+    </Tooltip>
   );
 }
diff --git a/src/frontend/src/pages/build/BuildDetail.tsx b/src/frontend/src/pages/build/BuildDetail.tsx
index 7a69f25f38..fe48207322 100644
--- a/src/frontend/src/pages/build/BuildDetail.tsx
+++ b/src/frontend/src/pages/build/BuildDetail.tsx
@@ -575,6 +575,7 @@ export default function BuildDetail() {
           />,
           <DetailsBadge
             label={t`External`}
+            tooltip={t`This build order is fulfilled by an external supplier`}
             color='blue'
             key='external'
             visible={build.external}
diff --git a/src/frontend/src/pages/company/CompanyDetail.tsx b/src/frontend/src/pages/company/CompanyDetail.tsx
index 94b94890d4..2c7b855f4b 100644
--- a/src/frontend/src/pages/company/CompanyDetail.tsx
+++ b/src/frontend/src/pages/company/CompanyDetail.tsx
@@ -277,6 +277,7 @@ export default function CompanyDetail(props: Readonly<CompanyDetailProps>) {
     return [
       <DetailsBadge
         label={t`Inactive`}
+        tooltip={t`This company is inactive`}
         color='red'
         visible={company.active == false}
       />
diff --git a/src/frontend/src/pages/company/SupplierPartDetail.tsx b/src/frontend/src/pages/company/SupplierPartDetail.tsx
index 23087de438..376a0f08d9 100644
--- a/src/frontend/src/pages/company/SupplierPartDetail.tsx
+++ b/src/frontend/src/pages/company/SupplierPartDetail.tsx
@@ -222,11 +222,13 @@ export default function SupplierPartDetail() {
     return [
       <DetailsBadge
         label={t`Inactive`}
+        tooltip={t`This supplier part is inactive`}
         color='red'
         visible={supplierPart.active == false}
       />,
       <DetailsBadge
         label={`${t`In Stock`}: ${formatDecimal(supplierPart.in_stock)}`}
+        tooltip={t`Quantity of this supplier part in stock`}
         color={'green'}
         visible={
           supplierPart?.active &&
@@ -237,12 +239,14 @@ export default function SupplierPartDetail() {
       />,
       <DetailsBadge
         label={t`No Stock`}
+        tooltip={t`There is no stock available for this supplier part`}
         color={'red'}
         visible={supplierPart.active && supplierPart.in_stock == 0}
         key='no_stock'
       />,
       <DetailsBadge
         label={`${t`On Order`}: ${formatDecimal(supplierPart.on_order)}`}
+        tooltip={t`Quantity on order from outstanding purchase orders`}
         color='blue'
         visible={supplierPart.on_order > 0}
         key='on_order'
diff --git a/src/frontend/src/pages/part/PartDetail.tsx b/src/frontend/src/pages/part/PartDetail.tsx
index 953ec52c00..22636c7068 100644
--- a/src/frontend/src/pages/part/PartDetail.tsx
+++ b/src/frontend/src/pages/part/PartDetail.tsx
@@ -571,12 +571,14 @@ export default function PartDetail() {
     return [
       <DetailsBadge
         label={`${t`In Stock`}: ${formatDecimal(partRequirements.total_stock)}`}
+        tooltip={t`Total quantity of this part in stock`}
         color={stockColor}
         visible={!part.virtual && partRequirements.total_stock > 0}
         key='in_stock'
       />,
       <DetailsBadge
         label={`${t`Available`}: ${formatDecimal(partRequirements.unallocated_stock)}`}
+        tooltip={t`Quantity of stock which is not allocated to orders`}
         color='yellow'
         key='available_stock'
         visible={
@@ -586,54 +588,63 @@ export default function PartDetail() {
       />,
       <DetailsBadge
         label={t`No Stock`}
+        tooltip={t`There is no stock available for this part`}
         color='orange'
         visible={!part.virtual && partRequirements.total_stock == 0}
         key='no_stock'
       />,
       <DetailsBadge
         label={`${t`Allocated`}: ${formatDecimal(allocated)}`}
+        tooltip={t`Quantity of stock allocated to orders`}
         color='blue'
         visible={allocated > 0}
         key='allocated'
       />,
       <DetailsBadge
         label={`${t`Required`}: ${formatDecimal(required)}`}
+        tooltip={t`Quantity required for outstanding orders`}
         color='grape'
         visible={required > 0}
         key='required'
       />,
       <DetailsBadge
         label={`${t`On Order`}: ${formatDecimal(partRequirements.ordering)}`}
+        tooltip={t`Quantity on order from outstanding purchase orders`}
         color='blue'
         visible={partRequirements.ordering > 0}
         key='on_order'
       />,
       <DetailsBadge
         label={`${t`In Production`}: ${formatDecimal(partRequirements.scheduled_to_build)}`}
+        tooltip={t`Quantity scheduled to be built by outstanding build orders`}
         color='blue'
         visible={partRequirements.scheduled_to_build > 0}
         key='in_production'
       />,
       <DetailsBadge
         label={`${t`Deficit`}: ${formatDecimal(shortfall)}`}
+        tooltip={t`Shortfall between total stock and required quantity`}
         color='red'
         visible={shortfall > 0}
         key='deficit'
       />,
       <DetailsBadge
         label={t`Inactive`}
+        tooltip={t`This part is inactive`}
         color='red'
         visible={!part.active}
         key='inactive'
       />,
       <DetailsBadge
         label={t`Virtual`}
+        tooltip={t`This is a virtual part, which is not tracked in stock`}
         color='cyan.4'
         visible={part.virtual}
         key='virtual'
       />,
       <DetailsBadge
         label={t`Consumable`}
+        tooltip={t`This is a consumable part`}
         color='cyan.4'
         visible={part.consumable}
         key='consumable'
diff --git a/src/frontend/src/pages/sales/SalesOrderShipmentDetail.tsx b/src/frontend/src/pages/sales/SalesOrderShipmentDetail.tsx
index edf444da05..b9a1d2a308 100644
--- a/src/frontend/src/pages/sales/SalesOrderShipmentDetail.tsx
+++ b/src/frontend/src/pages/sales/SalesOrderShipmentDetail.tsx
@@ -168,30 +168,35 @@ export default function SalesOrderShipmentDetail() {
       <DetailsBadge
         key='pending'
         label={t`Pending`}
+        tooltip={t`This shipment has not yet been sent`}
         color='gray'
         visible={isPending}
       />,
       <DetailsBadge
         key='checked'
         label={t`Checked`}
+        tooltip={t`This shipment has been checked`}
         color='green'
         visible={isPending && isChecked}
       />,
       <DetailsBadge
         key='not-checked'
         label={t`Not Checked`}
+        tooltip={t`This shipment has not been checked`}
         color='red'
         visible={isPending && !isChecked}
       />,
       <DetailsBadge
         key='shipped'
         label={t`Shipped`}
+        tooltip={t`This shipment has been sent`}
         color='green'
         visible={!isPending}
       />,
       <DetailsBadge
         key='delivered'
         label={t`Delivered`}
+        tooltip={t`This shipment has been delivered`}
         color='blue'
         visible={!!shipment.delivery_date}
       />
diff --git a/src/frontend/src/pages/stock/StockDetail.tsx b/src/frontend/src/pages/stock/StockDetail.tsx
index c06adae3e6..4244a62226 100644
--- a/src/frontend/src/pages/stock/StockDetail.tsx
+++ b/src/frontend/src/pages/stock/StockDetail.tsx
@@ -660,23 +660,27 @@ export default function StockDetail() {
           <DetailsBadge
             color='yellow'
             label={t`In Production`}
+            tooltip={t`This stock item is currently being built`}
             visible={stockitem.is_building}
           />,
           <DetailsBadge
             color='blue'
             label={`${t`Serial Number`}: ${stockitem.serial}`}
+            tooltip={t`Serial number of this stock item`}
             visible={!!stockitem.serial}
             key='serial'
           />,
           <DetailsBadge
             color='blue'
             label={`${t`Quantity`}: ${formatDecimal(stockitem.quantity)}`}
+            tooltip={t`Total quantity of this stock item`}
             visible={!stockitem.serial}
             key='quantity'
           />,
           <DetailsBadge
             color='yellow'
             label={`${t`Available`}: ${formatDecimal(available)}`}
+            tooltip={t`Quantity which is not allocated to orders`}
             visible={
               stockitem.in_stock &&
               !stockitem.serial &&
@@ -687,6 +691,7 @@ export default function StockDetail() {
           <DetailsBadge
             color='blue'
             label={`${t`Batch Code`}: ${stockitem.batch}`}
+            tooltip={t`Batch code of this stock item`}
             visible={!!stockitem.batch}
             key='batch'
           />,
@@ -702,18 +707,21 @@ export default function StockDetail() {
           <DetailsBadge
             color='yellow'
             label={t`Stale`}
+            tooltip={t`This stock item is approaching its expiry date`}
             visible={enableExpiry && stockitem.stale && !stockitem.expired}
             key='stale'
           />,
           <DetailsBadge
             color='orange'
             label={t`Expired`}
+            tooltip={t`This stock item has passed its expiry date`}
             visible={enableExpiry && stockitem.expired}
             key='expired'
           />,
           <DetailsBadge
             color='red'
             label={t`Unavailable`}
+            tooltip={t`This stock item is not available in stock`}
             visible={stockitem.in_stock == false}
             key='unavailable'
           />