cmk-frontend-vue: extract inline-edit outside-click/Escape behavior into a composable

The attribute-filter pill embedded the full lifecycle of an inline
edit that commits on click-outside and on Escape: arming the outside
handler one task after opening (so the opening click's tail bubble is
ignored), guarding against clicks that start inside the pane, and letting
an open dropdown swallow Escape before it closes the edit.

Pull that interaction into a reusable useInlineEdit composable that
owns only the mechanics and delegates what "leaving" means back to the
caller via an onLeave(reason) callback. The pill keeps its own
validation, commit and focus handling, the behaviour is unchanged, and
the interaction is now available to other inline edits.

Jira: CMK-35396
Change-Id: I2b79975d56db8462ac900a04921a51289645d98a

Author: whme

packages/cmk-frontend-vue/src/metric-backend/attribute-filter/AttributeFilterPill.vue

@@ -5,15 +5,15 @@ conditions defined in the file COPYING, which is part of this source code packag
 -->
 
 <script setup lang="ts">
-import { computed, nextTick, onBeforeUnmount, onMounted, ref, useTemplateRef, watch } from 'vue'
+import { computed, nextTick, ref, useTemplateRef, watch } from 'vue'
 
 import usei18n from '@/lib/i18n'
-import useClickOutside from '@/lib/useClickOutside'
 
 import CmkDropdown from '@/components/CmkDropdown/CmkDropdown.vue'
 import CmkIconButton from '@/components/CmkIconButton.vue'
 import type { QuerySuggestionsFn } from '@/components/CmkSuggestions/types'
 
+import useInlineEdit, { type InlineEditLeaveReason } from '../useInlineEdit'
 import { ATTRIBUTE_TYPE_LABELS, attributeTypePrefix, operatorPhrase, pillLabel } from './pill-label'
 import {
   EXISTENCE_OPERATORS,
@@ -26,8 +26,6 @@ import type { AttributeType, ConnectedCondition, Operator } from './types'
 
 const { _t } = usei18n()
 
-const vClickOutside = useClickOutside()
-
 const props = withDefaults(
   defineProps<{
     condition: ConnectedCondition
@@ -89,39 +87,18 @@ const validationVisible = computed(() => showValidationErrors.value)
 const closedPillRef = useTemplateRef<HTMLElement>('closedPillRef')
 let returnFocusToClosedPill = false
 
-// The click that creates a pill in edit mode keeps bubbling after Vue mounts
-// the new edit branch. Defer arming the outside-click handler by one task so
-// that tail bubble does not turn into the pill's own first commit attempt.
-let outsideArmed = false
-let armTimer: ReturnType<typeof setTimeout> | null = null
-function armOutsideNextTask(): void {
-  if (armTimer !== null) {
-    clearTimeout(armTimer)
-  }
-  armTimer = setTimeout(() => {
-    outsideArmed = true
-    armTimer = null
-  }, 0)
-}
-
 // Guided edit chain: each watcher auto-opens the next dropdown that still
 // needs input, minimizing clicks on the common path.
 watch(
   () => props.editing,
   (now) => {
     if (now) {
-      armOutsideNextTask()
       if (!props.condition.key) {
         void nextTick(() => keyDropdownRef.value?.open())
       } else {
         void nextTick(() => attributeTypeDropdownRef.value?.focus())
       }
     } else {
-      outsideArmed = false
-      if (armTimer !== null) {
-        clearTimeout(armTimer)
-        armTimer = null
-      }
       showValidationErrors.value = false
       if (returnFocusToClosedPill) {
         returnFocusToClosedPill = false
@@ -249,56 +226,29 @@ const operatorOptions = computed(() => {
 
 const hasValidationErrors = computed(() => !isConditionValid(props.condition))
 
-const editPaneRef = useTemplateRef<HTMLElement>('editPaneRef')
-
-// Prevent a click inside the edit pane from counting as outside and commiting the pill.
-let mousedownInside = false
-function onBodyMousedown(event: MouseEvent): void {
-  const target = event.target
-  mousedownInside =
-    editPaneRef.value !== null && target instanceof Node && editPaneRef.value.contains(target)
-}
-onMounted(() => {
-  document.addEventListener('mousedown', onBodyMousedown, true)
-})
-onBeforeUnmount(() => {
-  document.removeEventListener('mousedown', onBodyMousedown, true)
-})
-
-function onOutside(): void {
-  if (mousedownInside) {
-    mousedownInside = false
-    return
-  }
-  if (!outsideArmed) {
-    return
-  }
+// Clicking outside the edit pane, or pressing Escape, commits the pill — unless
+// a required field is still empty, in which case the errors are revealed and the
+// pill stays open. Escape additionally returns focus to the closed pill.
+function onLeave(reason: InlineEditLeaveReason): void {
   if (hasValidationErrors.value) {
     showValidationErrors.value = true
     return
   }
-  emit('done')
-}
-
-// Escape should close open Dropdown without commiting the pill
-let escapeAteDropdown = false
-function onEditEscapeCapture(): void {
-  escapeAteDropdown =
-    editPaneRef.value !== null && editPaneRef.value.querySelector('[aria-expanded="true"]') !== null
-}
-function onEditEscape(): void {
-  if (escapeAteDropdown) {
-    escapeAteDropdown = false
-    return
+  if (reason === 'escape') {
+    returnFocusToClosedPill = true
   }
-  if (hasValidationErrors.value) {
-    showValidationErrors.value = true
-    return
-  }
-  returnFocusToClosedPill = true
   emit('done')
 }
 
+const editPaneRef = useTemplateRef<HTMLElement>('editPaneRef')
+
+const {
+  vClickOutside,
+  onOutsideClick: onOutside,
+  onEscapeCapture: onEditEscapeCapture,
+  onEscape: onEditEscape
+} = useInlineEdit({ isOpen: () => props.editing, paneRef: editPaneRef, onLeave })
+
 defineExpose({
   revealValidationErrors: () => {
     showValidationErrors.value = true

packages/cmk-frontend-vue/src/metric-backend/useInlineEdit.ts

@@ -0,0 +1,127 @@
+/**
+ * Copyright (C) 2026 Checkmk GmbH - License: Checkmk Enterprise License
+ * This file is part of Checkmk (https://checkmk.com). It is subject to the terms and
+ * conditions defined in the file COPYING, which is part of this source code package.
+ */
+import { onBeforeUnmount, onMounted, watch } from 'vue'
+import type { Directive, ShallowRef } from 'vue'
+
+import useClickOutside from '@/lib/useClickOutside'
+
+export type InlineEditLeaveReason = 'outside' | 'escape'
+
+export interface UseInlineEditOptions {
+  /** Reactive getter telling whether the inline edit is currently open. */
+  isOpen: () => boolean
+  /**
+   * Template ref of the edit's bounding element (e.g. from `useTemplateRef`).
+   * Clicks beyond it, and Escape, are what leave the edit.
+   */
+  paneRef: Readonly<ShallowRef<HTMLElement | null>>
+  /**
+   * Called when the user leaves the open edit by clicking outside its bounds
+   * (`'outside'`) or pressing Escape (`'escape'`).
+   *
+   * Three spurious triggers are filtered out before this fires: clicks that
+   * started inside the edit, Escape presses consumed by an open dropdown, and
+   * the trailing bubble of the very click that opened the edit.
+   */
+  onLeave: (reason: InlineEditLeaveReason) => void
+}
+
+export interface InlineEdit {
+  /** Directive to bind as `v-click-outside` on the bounding element. */
+  vClickOutside: Directive
+  /** Handler to pass to `v-click-outside`. */
+  onOutsideClick: () => void
+  /** Handler for `@keydown.esc.capture`. */
+  onEscapeCapture: () => void
+  /** Handler for `@keydown.esc`. */
+  onEscape: () => void
+}
+
+/**
+ * Drives the open/close lifecycle of an inline edit that commits on
+ * click-outside and on Escape: an element that, while open, should leave edit
+ * mode when the user clicks beyond it or presses Escape.
+ *
+ * It owns only the interaction mechanics (arming, inside-click and dropdown
+ * guards) and delegates what "leaving" means to {@link UseInlineEditOptions.onLeave},
+ * so callers keep full control over validation, committing and focus handling.
+ */
+export default function useInlineEdit(options: UseInlineEditOptions): InlineEdit {
+  const { paneRef } = options
+  const vClickOutside = useClickOutside()
+
+  // The click that opens the editor keeps bubbling after Vue mounts the edit
+  // branch. Defer arming the outside-click handler by one task so that tail
+  // bubble does not turn into the editor's own first leave attempt.
+  let outsideArmed = false
+  let armTimer: ReturnType<typeof setTimeout> | null = null
+  function clearArmTimer(): void {
+    if (armTimer !== null) {
+      clearTimeout(armTimer)
+      armTimer = null
+    }
+  }
+
+  watch(
+    options.isOpen,
+    (open) => {
+      if (open) {
+        clearArmTimer()
+        armTimer = setTimeout(() => {
+          outsideArmed = true
+          armTimer = null
+        }, 0)
+      } else {
+        outsideArmed = false
+        clearArmTimer()
+      }
+    },
+    { immediate: true }
+  )
+
+  // Prevent a click that starts inside the editor from counting as outside and
+  // leaving edit mode.
+  let mousedownInside = false
+  function onBodyMousedown(event: MouseEvent): void {
+    const target = event.target
+    mousedownInside =
+      paneRef.value !== null && target instanceof Node && paneRef.value.contains(target)
+  }
+  onMounted(() => {
+    document.addEventListener('mousedown', onBodyMousedown, true)
+  })
+  onBeforeUnmount(() => {
+    document.removeEventListener('mousedown', onBodyMousedown, true)
+    clearArmTimer()
+  })
+
+  function onOutsideClick(): void {
+    if (mousedownInside) {
+      mousedownInside = false
+      return
+    }
+    if (!outsideArmed) {
+      return
+    }
+    options.onLeave('outside')
+  }
+
+  // Escape should close an open dropdown without leaving the editor.
+  let escapeAteDropdown = false
+  function onEscapeCapture(): void {
+    escapeAteDropdown =
+      paneRef.value !== null && paneRef.value.querySelector('[aria-expanded="true"]') !== null
+  }
+  function onEscape(): void {
+    if (escapeAteDropdown) {
+      escapeAteDropdown = false
+      return
+    }
+    options.onLeave('escape')
+  }
+
+  return { vClickOutside, onOutsideClick, onEscapeCapture, onEscape }
+}

packages/cmk-frontend-vue/tests/metric-backend/useInlineEdit.test.ts

@@ -0,0 +1,97 @@
+/**
+ * Copyright (C) 2026 Checkmk GmbH - License: GNU General Public License v2
+ * This file is part of Checkmk (https://checkmk.com). It is subject to the terms and
+ * conditions defined in the file COPYING, which is part of this source code package.
+ */
+import { render } from '@testing-library/vue'
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+import type { Ref } from 'vue'
+import { defineComponent, h, nextTick, ref, useTemplateRef } from 'vue'
+
+import useInlineEdit from '@/metric-backend/useInlineEdit'
+
+// Mount a host that drives the composable and renders a real pane element bound
+// to the `paneRef` template ref it passes in, so the document mousedown-capture
+// listener fires and `paneRef.value.contains(...)` resolves against an attached
+// DOM subtree.
+function mountEditor(open: Ref<boolean>) {
+  const onLeave = vi.fn()
+  let api!: ReturnType<typeof useInlineEdit>
+  const host = defineComponent({
+    setup() {
+      const paneRef = useTemplateRef<HTMLElement>('editPaneRef')
+      api = useInlineEdit({ isOpen: () => open.value, paneRef, onLeave })
+      return () =>
+        open.value
+          ? h('div', { ref: 'editPaneRef', 'data-pane': '' }, [h('span', { 'data-inside': '' })])
+          : null
+    }
+  })
+  render(host)
+  return { api, onLeave }
+}
+
+function inside(): HTMLElement {
+  return document.querySelector<HTMLElement>('[data-pane] [data-inside]')!
+}
+
+describe('useInlineEdit', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  test('does not leave on the opening click tail bubble, only once armed', async () => {
+    const open = ref(false)
+    const { api, onLeave } = mountEditor(open)
+
+    open.value = true
+    await nextTick()
+
+    // The click that opened the editor keeps bubbling; before the arm timer
+    // fires it must not count as the editor's own first leave.
+    api.onOutsideClick()
+    expect(onLeave).not.toHaveBeenCalled()
+
+    vi.advanceTimersByTime(0)
+    api.onOutsideClick()
+    expect(onLeave).toHaveBeenCalledTimes(1)
+    expect(onLeave).toHaveBeenCalledWith('outside')
+  })
+
+  test('suppresses an outside click whose mousedown started inside the pane', () => {
+    const open = ref(true)
+    const { api, onLeave } = mountEditor(open)
+    vi.advanceTimersByTime(0) // arm
+
+    inside().dispatchEvent(new MouseEvent('mousedown', { bubbles: true }))
+    api.onOutsideClick()
+    expect(onLeave).not.toHaveBeenCalled()
+
+    // A subsequent click that started outside still leaves.
+    document.body.dispatchEvent(new MouseEvent('mousedown', { bubbles: true }))
+    api.onOutsideClick()
+    expect(onLeave).toHaveBeenCalledTimes(1)
+    expect(onLeave).toHaveBeenCalledWith('outside')
+  })
+
+  test('lets an open dropdown swallow Escape instead of leaving', () => {
+    const open = ref(true)
+    const { api, onLeave } = mountEditor(open)
+    inside().setAttribute('aria-expanded', 'true')
+
+    api.onEscapeCapture()
+    api.onEscape()
+    expect(onLeave).not.toHaveBeenCalled()
+
+    // With no dropdown open, the next Escape leaves the editor.
+    inside().removeAttribute('aria-expanded')
+    api.onEscapeCapture()
+    api.onEscape()
+    expect(onLeave).toHaveBeenCalledTimes(1)
+    expect(onLeave).toHaveBeenCalledWith('escape')
+  })
+})