From eabb34815288e4ffa99e289a9984d6ec0bd71a2d Mon Sep 17 00:00:00 2001
From: Paul Marbach <paul.marbach@grafana.com>
Date: Fri, 24 Oct 2025 15:04:33 -0400
Subject: [PATCH] StateTimeline: Comment and metadata cleanup (#112960)

---
 eslint.config.js                              | 19 +++++++++++++++++++
 .../state-timeline/StateTimelinePanel.tsx     |  3 ---
 .../plugins/panel/state-timeline/hooks.tsx    |  7 +++++++
 3 files changed, 26 insertions(+), 3 deletions(-)

diff --git a/eslint.config.js b/eslint.config.js
index f01463559aa..b88a4231fd3 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -485,6 +485,25 @@ module.exports = [
     },
   },
 
+  // dataviz prefers to use `clsx` over `cx` to compose classes as a rule for performance reasons
+  {
+    files: ['public/app/plugins/panel/state-timeline/**/*.{ts,tsx}'],
+    rules: {
+      'no-restricted-imports': [
+        'error',
+        withBaseRestrictedImportsConfig({
+          patterns: [
+            {
+              group: ['@emotion/css'],
+              importNames: ['cx'],
+              message: 'Do not use "cx" from @emotion/css. Instead, use `clsx` and compose together only strings.',
+            },
+          ],
+        }),
+      ],
+    },
+  },
+
   // Old betterer rules config:
   {
     files: ['**/*.{js,jsx,ts,tsx}'],
diff --git a/public/app/plugins/panel/state-timeline/StateTimelinePanel.tsx b/public/app/plugins/panel/state-timeline/StateTimelinePanel.tsx
index 8dffba2ad0d..59883b946c4 100644
--- a/public/app/plugins/panel/state-timeline/StateTimelinePanel.tsx
+++ b/public/app/plugins/panel/state-timeline/StateTimelinePanel.tsx
@@ -29,9 +29,6 @@ import { containerStyles } from './styles';
 
 interface TimelinePanelProps extends PanelProps<Options> {}
 
-/**
- * @alpha
- */
 export const StateTimelinePanel = ({
   data,
   timeRange,
diff --git a/public/app/plugins/panel/state-timeline/hooks.tsx b/public/app/plugins/panel/state-timeline/hooks.tsx
index 9d23d2cf21e..c52c6adbf87 100644
--- a/public/app/plugins/panel/state-timeline/hooks.tsx
+++ b/public/app/plugins/panel/state-timeline/hooks.tsx
@@ -17,6 +17,13 @@ const paginationStyles = {
   }),
 };
 
+/**
+ * a React hook used to encapsulate the rendering and state for pagination in StateTimeline.
+ * @param frames DataFrames to paginate
+ * @param perPage number of series per page
+ * @returns the current frames rendered, the pagination element to render, the height of the pagination element,
+ *    and a paginationRev which GraphNG uses to trigger re-renders.
+ */
 export function usePagination(frames?: DataFrame[], perPage?: number) {
   const [currentPage, setCurrentPage] = useState(1);