From 631f87a4155f40bcd8505480f040e184a307abae Mon Sep 17 00:00:00 2001
From: Leif Singer <leif@ghost.org>
Date: Thu, 18 Sep 2025 14:36:18 +0200
Subject: [PATCH 1/8]   feat(TKPlugin): implemented list-item-level TK
 detection and positioning

  Previously, TK monikers in bulleted lists were tracked at the <ul> level,
  making it difficult for authors to identify which specific list items
  contained incomplete content. This change implements list-aware TK detection
  that treats each <li> element as an individual container.

  - Added getEffectiveTopLevelElement() to recognize list items as containers
  - Updated mutation listener to use list-aware detection logic
  - Enhanced positioning calculations for precise list item indicator placement
  - Added comprehensive test coverage for list-specific TK behavior

  This provides authors with granular visibility into which list items need
  completion, consistent with how TK tracking works for paragraph elements.

  Fixes PROD-2389
---
 .../koenig-lexical/src/plugins/TKPlugin.jsx   | 37 ++++++++++++++++++-
 .../test/e2e/plugins/TKPlugin.test.js         | 36 ++++++++++++++++++
 2 files changed, 71 insertions(+), 2 deletions(-)

diff --git a/packages/koenig-lexical/src/plugins/TKPlugin.jsx b/packages/koenig-lexical/src/plugins/TKPlugin.jsx
index 320ad7109f..a7dd57da78 100644
--- a/packages/koenig-lexical/src/plugins/TKPlugin.jsx
+++ b/packages/koenig-lexical/src/plugins/TKPlugin.jsx
@@ -11,6 +11,32 @@ import {useTKContext} from '../context/TKContext';
 const REGEX = new RegExp(/(^|.)([^\p{L}\p{N}\s]*(TK|Tk|tk)+[^\p{L}\p{N}\s]*)(.)?/u);
 const WORD_CHAR_REGEX = new RegExp(/\p{L}|\p{N}/u);
 
+// Helper function to get effective top-level element, treating list items as containers
+function getEffectiveTopLevelElement(node) {
+    const topLevel = node.getTopLevelElement();
+
+    if (!topLevel) {
+        return null;
+    }
+
+    // Get the DOM element to check if it's a list
+    const domElement = topLevel.getDOMNode?.() || topLevel.__domNode;
+
+    if (domElement && (domElement.nodeName === 'UL' || domElement.nodeName === 'OL')) {
+        // For lists, find the containing list item instead
+        let currentNode = node;
+        while (currentNode && !currentNode.isRoot()) {
+            const domNode = currentNode.getDOMNode?.() || currentNode.__domNode;
+            if (domNode && domNode.nodeName === 'LI') {
+                return currentNode;
+            }
+            currentNode = currentNode.getParent();
+        }
+    }
+
+    return topLevel;
+}
+
 function TKIndicator({editor, rootElement, parentKey, nodeKeys}) {
     const tkClasses = editor._config.theme.tk?.split(' ') || [];
     const tkHighlightClasses = editor._config.theme.tkHighlighted?.split(' ') || [];
@@ -24,7 +50,13 @@ function TKIndicator({editor, rootElement, parentKey, nodeKeys}) {
 
         const rootElementRect = rootElement.getBoundingClientRect();
 
-        const positioningElement = containingElement.querySelector('[data-kg-card]') || containingElement;
+        let positioningElement = containingElement.querySelector('[data-kg-card]') || containingElement;
+
+        // For list items, use more precise positioning
+        if (containingElement.nodeName === 'LI') {
+            positioningElement = containingElement;
+        }
+
         const positioningElementRect = positioningElement.getBoundingClientRect();
 
         top = positioningElementRect.top - rootElementRect.top + 4;
@@ -157,7 +189,8 @@ export default function TKPlugin() {
                     if (mutation === 'destroyed') {
                         removeEditorTkNode(editor.getKey(), tkNodeKey);
                     } else {
-                        const parentNodeKey = $getNodeByKey(tkNodeKey).getTopLevelElement()?.getKey();
+                        const effectiveTopLevel = getEffectiveTopLevelElement($getNodeByKey(tkNodeKey));
+                        const parentNodeKey = effectiveTopLevel?.getKey();
                         const topLevelNodeKey = parentEditorNodeKey || parentNodeKey;
                         addEditorTkNode(editor.getKey(), topLevelNodeKey, tkNodeKey);
                     }
diff --git a/packages/koenig-lexical/test/e2e/plugins/TKPlugin.test.js b/packages/koenig-lexical/test/e2e/plugins/TKPlugin.test.js
index 134c6efa24..2a28e9e412 100644
--- a/packages/koenig-lexical/test/e2e/plugins/TKPlugin.test.js
+++ b/packages/koenig-lexical/test/e2e/plugins/TKPlugin.test.js
@@ -115,6 +115,42 @@ test.describe('TK Plugin', async function () {
             await expect(page.getByTestId('tk-indicator')).toHaveCount(3);
         });
 
+        test('creates separate TK indicators for each list item containing TK', async function () {
+            await focusEditor(page);
+
+            await page.keyboard.type('- First item with TK');
+            await page.keyboard.press('Enter');
+            await page.keyboard.type('Second item with TK');
+            await page.keyboard.press('Enter');
+            await page.keyboard.type('Third item without placeholder');
+            await page.keyboard.press('Enter');
+            await page.keyboard.type('Fourth item with TK');
+
+            // Should have 3 separate TK indicators, one for each list item containing TK
+            await expect(page.getByTestId('tk-indicator')).toHaveCount(3);
+        });
+
+        test('positions TK indicators correctly for individual list items', async function () {
+            await focusEditor(page);
+
+            await page.keyboard.type('- First TK item');
+            await page.keyboard.press('Enter');
+            await page.keyboard.type('Second TK item');
+
+            const indicators = page.getByTestId('tk-indicator');
+            await expect(indicators).toHaveCount(2);
+
+            // Get positions to verify they're different (one per list item)
+            const firstIndicator = indicators.first();
+            const secondIndicator = indicators.last();
+
+            const firstBox = await firstIndicator.boundingBox();
+            const secondBox = await secondIndicator.boundingBox();
+
+            // The indicators should have different vertical positions
+            expect(Math.abs(firstBox.y - secondBox.y)).toBeGreaterThan(10);
+        });
+
         test('clicking the indicator selects the first TK node in the parent', async function () {
             await focusEditor(page);
             await page.keyboard.type('TK and TK and TK');

From 91e62ec370b03a15d1a5cdb60b7944a95a4d1521 Mon Sep 17 00:00:00 2001
From: Leif Singer <leif@ghost.org>
Date: Thu, 18 Sep 2025 15:02:09 +0200
Subject: [PATCH 2/8]   fix(TKPlugin): correct Lexical node type checking for
 list item detection

  Fixed TypeError in getEffectiveTopLevelElement where currentNode.isRoot()
  method doesn't exist. Replaced with proper Lexical node parent checking
  using currentNode.getParent() !== null to traverse the node hierarchy
  correctly when identifying list items as TK containers.

  Fixes PROD-2389
---
 packages/koenig-lexical/src/plugins/TKPlugin.jsx | 13 +++++--------
 1 file changed, 5 insertions(+), 8 deletions(-)

diff --git a/packages/koenig-lexical/src/plugins/TKPlugin.jsx b/packages/koenig-lexical/src/plugins/TKPlugin.jsx
index a7dd57da78..b05ac61289 100644
--- a/packages/koenig-lexical/src/plugins/TKPlugin.jsx
+++ b/packages/koenig-lexical/src/plugins/TKPlugin.jsx
@@ -1,6 +1,7 @@
 import CardContext from '../context/CardContext';
 import {$createTKNode, $isTKNode, ExtendedTextNode, TKNode} from '@tryghost/kg-default-nodes';
 import {$getNodeByKey, $getSelection, $isDecoratorNode, $isRangeSelection, TextNode} from 'lexical';
+import {$isListItemNode, $isListNode} from '@lexical/list';
 import {SELECT_CARD_COMMAND} from './KoenigBehaviourPlugin';
 import {createPortal} from 'react-dom';
 import {useCallback, useContext, useEffect, useState} from 'react';
@@ -19,15 +20,11 @@ function getEffectiveTopLevelElement(node) {
         return null;
     }
 
-    // Get the DOM element to check if it's a list
-    const domElement = topLevel.getDOMNode?.() || topLevel.__domNode;
-
-    if (domElement && (domElement.nodeName === 'UL' || domElement.nodeName === 'OL')) {
-        // For lists, find the containing list item instead
+    // If the top-level element is a list, find the containing list item instead
+    if ($isListNode(topLevel)) {
         let currentNode = node;
-        while (currentNode && !currentNode.isRoot()) {
-            const domNode = currentNode.getDOMNode?.() || currentNode.__domNode;
-            if (domNode && domNode.nodeName === 'LI') {
+        while (currentNode && currentNode.getParent() !== null) {
+            if ($isListItemNode(currentNode)) {
                 return currentNode;
             }
             currentNode = currentNode.getParent();

From 3c7600501a1d57609049e50017b9e52b07771f0f Mon Sep 17 00:00:00 2001
From: Leif Singer <leif@ghost.org>
Date: Thu, 18 Sep 2025 15:22:05 +0200
Subject: [PATCH 3/8] refactor(TKPlugin): extract magic numbers into named
 constants

- Add INDICATOR_OFFSET_RIGHT and INDICATOR_OFFSET_TOP constants
- Add NODE_TYPES constant for element type checking
- Improves code readability and maintainability
---
 packages/koenig-lexical/src/plugins/TKPlugin.jsx | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/packages/koenig-lexical/src/plugins/TKPlugin.jsx b/packages/koenig-lexical/src/plugins/TKPlugin.jsx
index b05ac61289..6c5fcfab3f 100644
--- a/packages/koenig-lexical/src/plugins/TKPlugin.jsx
+++ b/packages/koenig-lexical/src/plugins/TKPlugin.jsx
@@ -12,6 +12,15 @@ import {useTKContext} from '../context/TKContext';
 const REGEX = new RegExp(/(^|.)([^\p{L}\p{N}\s]*(TK|Tk|tk)+[^\p{L}\p{N}\s]*)(.)?/u);
 const WORD_CHAR_REGEX = new RegExp(/\p{L}|\p{N}/u);
 
+// TK Indicator positioning constants
+const INDICATOR_OFFSET_RIGHT = -56;
+const INDICATOR_OFFSET_TOP = 4;
+
+// Node type constants
+const NODE_TYPES = {
+    LIST_ITEM: 'LI'
+};
+
 // Helper function to get effective top-level element, treating list items as containers
 function getEffectiveTopLevelElement(node) {
     const topLevel = node.getTopLevelElement();
@@ -43,7 +52,7 @@ function TKIndicator({editor, rootElement, parentKey, nodeKeys}) {
     // position element relative to the TK Node containing element
     const calculatePosition = useCallback(() => {
         let top = 0;
-        let right = -56;
+        let right = INDICATOR_OFFSET_RIGHT;
 
         const rootElementRect = rootElement.getBoundingClientRect();
 
@@ -56,7 +65,7 @@ function TKIndicator({editor, rootElement, parentKey, nodeKeys}) {
 
         const positioningElementRect = positioningElement.getBoundingClientRect();
 
-        top = positioningElementRect.top - rootElementRect.top + 4;
+        top = positioningElementRect.top - rootElementRect.top + INDICATOR_OFFSET_TOP;
 
         if (positioningElementRect.right > rootElementRect.right) {
             right = right - (positioningElementRect.right - rootElementRect.right);

From 7eb33a2fe5b3237cfa803f3551e39a0e3b6c18c0 Mon Sep 17 00:00:00 2001
From: Leif Singer <leif@ghost.org>
Date: Thu, 18 Sep 2025 15:22:22 +0200
Subject: [PATCH 4/8] refactor(TKPlugin): improve getEffectiveTopLevelElement
 robustness

- Use early return for non-list elements for better readability
- Use optional chaining for safer null checking in while loop
- Add explicit fallback comment for clarity
- Restructure logic flow to be more maintainable
---
 .../koenig-lexical/src/plugins/TKPlugin.jsx   | 20 +++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/packages/koenig-lexical/src/plugins/TKPlugin.jsx b/packages/koenig-lexical/src/plugins/TKPlugin.jsx
index 6c5fcfab3f..4d44ad76af 100644
--- a/packages/koenig-lexical/src/plugins/TKPlugin.jsx
+++ b/packages/koenig-lexical/src/plugins/TKPlugin.jsx
@@ -29,17 +29,21 @@ function getEffectiveTopLevelElement(node) {
         return null;
     }
 
-    // If the top-level element is a list, find the containing list item instead
-    if ($isListNode(topLevel)) {
-        let currentNode = node;
-        while (currentNode && currentNode.getParent() !== null) {
-            if ($isListItemNode(currentNode)) {
-                return currentNode;
-            }
-            currentNode = currentNode.getParent();
+    // If the top-level element is not a list, return it directly
+    if (!$isListNode(topLevel)) {
+        return topLevel;
+    }
+
+    // Find the containing list item for list nodes
+    let currentNode = node;
+    while (currentNode?.getParent()) {
+        if ($isListItemNode(currentNode)) {
+            return currentNode;
         }
+        currentNode = currentNode.getParent();
     }
 
+    // Fallback to top-level element if no list item found
     return topLevel;
 }
 

From a6905d0a6ec075119438f874f4e97cc8c8acd2c4 Mon Sep 17 00:00:00 2001
From: Leif Singer <leif@ghost.org>
Date: Thu, 18 Sep 2025 15:22:38 +0200
Subject: [PATCH 5/8] refactor(TKPlugin): consolidate element queries for
 positioning

- Replace conditional assignment with ternary operator
- Use NODE_TYPES constant for element type checking
- Eliminate redundant element queries
- More concise and readable code
---
 packages/koenig-lexical/src/plugins/TKPlugin.jsx | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/packages/koenig-lexical/src/plugins/TKPlugin.jsx b/packages/koenig-lexical/src/plugins/TKPlugin.jsx
index 4d44ad76af..8d37521a3a 100644
--- a/packages/koenig-lexical/src/plugins/TKPlugin.jsx
+++ b/packages/koenig-lexical/src/plugins/TKPlugin.jsx
@@ -60,12 +60,10 @@ function TKIndicator({editor, rootElement, parentKey, nodeKeys}) {
 
         const rootElementRect = rootElement.getBoundingClientRect();
 
-        let positioningElement = containingElement.querySelector('[data-kg-card]') || containingElement;
-
-        // For list items, use more precise positioning
-        if (containingElement.nodeName === 'LI') {
-            positioningElement = containingElement;
-        }
+        // Determine positioning element based on container type
+        const positioningElement = containingElement.nodeName === NODE_TYPES.LIST_ITEM
+            ? containingElement
+            : containingElement.querySelector('[data-kg-card]') || containingElement;
 
         const positioningElementRect = positioningElement.getBoundingClientRect();
 

From c3aec84efba5812b3767a986baf36d59e25f1c80 Mon Sep 17 00:00:00 2001
From: Leif Singer <leif@ghost.org>
Date: Thu, 18 Sep 2025 15:23:04 +0200
Subject: [PATCH 6/8] refactor(TKPlugin): add error boundaries for
 getElementByKey calls

- Add null check for containingElement in TKIndicator
- Add element validation in toggleHighlightClasses forEach loop
- Return null instead of false for consistency in map filter
- Prevents potential runtime errors when DOM elements are unavailable
---
 .../koenig-lexical/src/plugins/TKPlugin.jsx    | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/packages/koenig-lexical/src/plugins/TKPlugin.jsx b/packages/koenig-lexical/src/plugins/TKPlugin.jsx
index 8d37521a3a..90bcb55309 100644
--- a/packages/koenig-lexical/src/plugins/TKPlugin.jsx
+++ b/packages/koenig-lexical/src/plugins/TKPlugin.jsx
@@ -53,6 +53,11 @@ function TKIndicator({editor, rootElement, parentKey, nodeKeys}) {
 
     const containingElement = editor.getElementByKey(parentKey);
 
+    // Early return if containing element is not available
+    if (!containingElement) {
+        return null;
+    }
+
     // position element relative to the TK Node containing element
     const calculatePosition = useCallback(() => {
         let top = 0;
@@ -123,12 +128,15 @@ function TKIndicator({editor, rootElement, parentKey, nodeKeys}) {
         }
 
         nodeKeys.forEach((key) => {
+            const element = editor.getElementByKey(key);
+            if (!element) return;
+
             if (isHighlighted) {
-                editor.getElementByKey(key).classList.remove(...tkClasses);
-                editor.getElementByKey(key).classList.add(...tkHighlightClasses);
+                element.classList.remove(...tkClasses);
+                element.classList.add(...tkHighlightClasses);
             } else {
-                editor.getElementByKey(key).classList.add(...tkClasses);
-                editor.getElementByKey(key).classList.remove(...tkHighlightClasses);
+                element.classList.add(...tkClasses);
+                element.classList.remove(...tkHighlightClasses);
             }
         });
     };
@@ -288,7 +296,7 @@ export default function TKPlugin() {
         const parentContainer = editor.getElementByKey(parentKey);
 
         if (!parentContainer) {
-            return false;
+            return null;
         }
 
         return (

From bd7544d3e6398cf673e17b3aba75889454ef59aa Mon Sep 17 00:00:00 2001
From: Leif Singer <leif@ghost.org>
Date: Thu, 18 Sep 2025 15:32:16 +0200
Subject: [PATCH 7/8] fix(TKPlugin): resolve React Hooks linting errors

- Move null check for containingElement after all hooks
- Add proper curly braces for if statement return
- Ensures hooks are called in consistent order per React rules
---
 packages/koenig-lexical/src/plugins/TKPlugin.jsx | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/packages/koenig-lexical/src/plugins/TKPlugin.jsx b/packages/koenig-lexical/src/plugins/TKPlugin.jsx
index 90bcb55309..56b8b2dbde 100644
--- a/packages/koenig-lexical/src/plugins/TKPlugin.jsx
+++ b/packages/koenig-lexical/src/plugins/TKPlugin.jsx
@@ -53,11 +53,6 @@ function TKIndicator({editor, rootElement, parentKey, nodeKeys}) {
 
     const containingElement = editor.getElementByKey(parentKey);
 
-    // Early return if containing element is not available
-    if (!containingElement) {
-        return null;
-    }
-
     // position element relative to the TK Node containing element
     const calculatePosition = useCallback(() => {
         let top = 0;
@@ -129,7 +124,9 @@ function TKIndicator({editor, rootElement, parentKey, nodeKeys}) {
 
         nodeKeys.forEach((key) => {
             const element = editor.getElementByKey(key);
-            if (!element) return;
+            if (!element) {
+                return;
+            }
 
             if (isHighlighted) {
                 element.classList.remove(...tkClasses);
@@ -163,6 +160,11 @@ function TKIndicator({editor, rootElement, parentKey, nodeKeys}) {
         };
     }, [rootElement, containingElement, calculatePosition]);
 
+    // Early return if containing element is not available (after all hooks)
+    if (!containingElement) {
+        return null;
+    }
+
     const style = {
         top: `${position.top}px`,
         right: `${position.right}px`

From 432e5f0efd54033cb9e6cab783157b368440e79e Mon Sep 17 00:00:00 2001
From: Leif Singer <leif@ghost.org>
Date: Thu, 18 Sep 2025 15:42:27 +0200
Subject: [PATCH 8/8] refactor(TKPlugin): improve positioning calculation
 architecture

- Extract positioning logic into dedicated helper functions
- Consolidate getPositioningElement and calculateRightOffset functions
- Simplify calculatePosition callback with cleaner, more readable flow
- Improve separation of concerns and maintainability
---
 .../koenig-lexical/src/plugins/TKPlugin.jsx   | 38 ++++++++++---------
 1 file changed, 21 insertions(+), 17 deletions(-)

diff --git a/packages/koenig-lexical/src/plugins/TKPlugin.jsx b/packages/koenig-lexical/src/plugins/TKPlugin.jsx
index 56b8b2dbde..e69b15072a 100644
--- a/packages/koenig-lexical/src/plugins/TKPlugin.jsx
+++ b/packages/koenig-lexical/src/plugins/TKPlugin.jsx
@@ -21,6 +21,21 @@ const NODE_TYPES = {
     LIST_ITEM: 'LI'
 };
 
+// Positioning helper functions
+function getPositioningElement(containingElement) {
+    return containingElement.nodeName === NODE_TYPES.LIST_ITEM
+        ? containingElement
+        : containingElement.querySelector('[data-kg-card]') || containingElement;
+}
+
+function calculateRightOffset(elementRect, rootRect) {
+    let right = INDICATOR_OFFSET_RIGHT;
+    if (elementRect.right > rootRect.right) {
+        right = right - (elementRect.right - rootRect.right);
+    }
+    return right;
+}
+
 // Helper function to get effective top-level element, treating list items as containers
 function getEffectiveTopLevelElement(node) {
     const topLevel = node.getTopLevelElement();
@@ -53,25 +68,14 @@ function TKIndicator({editor, rootElement, parentKey, nodeKeys}) {
 
     const containingElement = editor.getElementByKey(parentKey);
 
-    // position element relative to the TK Node containing element
+    // Calculate indicator position relative to the root element
     const calculatePosition = useCallback(() => {
-        let top = 0;
-        let right = INDICATOR_OFFSET_RIGHT;
+        const rootRect = rootElement.getBoundingClientRect();
+        const positioningElement = getPositioningElement(containingElement);
+        const elementRect = positioningElement.getBoundingClientRect();
 
-        const rootElementRect = rootElement.getBoundingClientRect();
-
-        // Determine positioning element based on container type
-        const positioningElement = containingElement.nodeName === NODE_TYPES.LIST_ITEM
-            ? containingElement
-            : containingElement.querySelector('[data-kg-card]') || containingElement;
-
-        const positioningElementRect = positioningElement.getBoundingClientRect();
-
-        top = positioningElementRect.top - rootElementRect.top + INDICATOR_OFFSET_TOP;
-
-        if (positioningElementRect.right > rootElementRect.right) {
-            right = right - (positioningElementRect.right - rootElementRect.right);
-        }
+        const top = elementRect.top - rootRect.top + INDICATOR_OFFSET_TOP;
+        const right = calculateRightOffset(elementRect, rootRect);
 
         return {top, right};
     }, [rootElement, containingElement]);