fix(hub-ui): keep edge dock entries reachable in limited space

Measure the edge toolbar and move entries that do not fit into the existing
overflow menu while reserving space for Settings. Preserve entry order and
allow single-entry overflow when category dividers prevent an inline fit.

Dismiss anchored group and overflow menus when their buttons unmount, and
keep the toolbar expanded while its overflow menu is open.

Author: SaKaNa-Y

packages/hub-ui/src/client/components/dock/DockEdge.vue

@@ -1,18 +1,22 @@
 <script setup lang="ts">
 import type { DocksContext } from '@devframes/hub/client'
 import type { CSSProperties } from 'vue'
+import type { DevframeDockEntriesGrouped } from '../../state/dock-settings'
 import type { DockEdge as DockEdgePosition, DockLayout } from './dock-layout'
 import { useEventListener } from '@vueuse/core'
-import { computed, h, onMounted, ref, useTemplateRef } from 'vue'
-import { getEntryGroup } from '../../state/dock-settings'
-import { setEdgePositionDropdown, setFloatingTooltip, useDocksGroupPanel, useEdgePositionDropdown } from '../../state/floating-tooltip'
+import { computed, h, onMounted, ref, useTemplateRef, watch } from 'vue'
+import { BUILTIN_ENTRY_SETTINGS } from '../../constants'
+import { docksSplitGroupsBySize, getEntryGroup } from '../../state/dock-settings'
+import { setEdgePositionDropdown, setFloatingTooltip, useDocksGroupPanel, useDocksOverflowPanel, useEdgePositionDropdown } from '../../state/floating-tooltip'
 import { useSettings } from '../../state/settings-defaults'
 import { getEntryPaneKey, useIframePanes } from '../../utils/useIframePanes'
 import BrandMark from '../icons/BrandMark.vue'
 import ViewEntry from '../views/ViewEntry.vue'
 import { resolveDockEdge, resolveDockLayout } from './dock-layout'
+import DockEntries from './DockEntries.vue'
 import DockEntriesWithCategories from './DockEntriesWithCategories.vue'
 import DockGroupSidebar from './DockGroupSidebar.vue'
+import DockOverflowButton from './DockOverflowButton.vue'
 import DockPanelResizer from './DockPanelResizer.vue'
 
 const props = defineProps<{
@@ -31,7 +35,43 @@ const panes = useIframePanes(viewsContainer, context.panel, () => getEntryPaneKe
 
 const isVertical = computed(() => store.position === 'left' || store.position === 'right')
 
-const groupedEntries = computed(() => context.docks.groupedEntries)
+const settingsEntries = computed(() => context.docks.groupedEntries.flatMap(([, entries]) => entries.filter(entry => entry.id === BUILTIN_ENTRY_SETTINGS.id)))
+const groupedEntries = computed(() => context.docks.groupedEntries
+  .map(([category, entries]): DevframeDockEntriesGrouped[number] => [category, entries.filter(entry => entry.id !== BUILTIN_ENTRY_SETTINGS.id)])
+  .filter(([, entries]) => entries.length > 0))
+const toolbarEntries = useTemplateRef<HTMLElement>('toolbarEntries')
+const settingsDock = useTemplateRef<HTMLElement>('settingsDock')
+const toolbarSize = ref({ width: 0, height: 0, item: 32, gap: 2 })
+
+watch([toolbarEntries, settingsDock], ([el, pinned], _prev, onCleanup) => {
+  if (!el || !pinned)
+    return
+  const view = el.ownerDocument.defaultView
+  const ResizeObserverCtor = view?.ResizeObserver ?? globalThis.ResizeObserver
+  if (!ResizeObserverCtor)
+    return
+  const observer = new ResizeObserverCtor((entries) => {
+    const bounds = entries.find(entry => entry.target === el)?.contentRect
+    const style = view?.getComputedStyle(el)
+    toolbarSize.value = {
+      width: bounds?.width ?? toolbarSize.value.width,
+      height: bounds?.height ?? toolbarSize.value.height,
+      item: pinned.querySelector('button')?.offsetWidth || 32,
+      gap: Number.parseFloat(style?.columnGap ?? '') || 0,
+    }
+  })
+  observer.observe(el)
+  observer.observe(pinned)
+  onCleanup(() => observer.disconnect())
+}, { immediate: true, flush: 'post' })
+
+const splitEntries = computed(() => {
+  const { width, height, item, gap } = toolbarSize.value
+  // Category dividers use m1 (four gap-0.5 units) and a 1.5px border.
+  const separatorSize = gap * 4 + 1.5
+  const settingsSize = settingsEntries.value.length ? item + separatorSize + gap * 2 : 0
+  return docksSplitGroupsBySize(groupedEntries.value, (isVertical.value ? height : width) - settingsSize, item, gap, separatorSize)
+})
 const selectedEntry = computed(() => context.docks.selected)
 const activeGroup = computed(() => getEntryGroup(context.docks.entries, selectedEntry.value))
 const hasPanelContent = computed(() => {
@@ -59,9 +99,10 @@ function bringUp() {
   }, +store.inactiveTimeout || 0)
 }
 
-// An open group menu popover anchors to a toolbar button, so collapsing the
+// An open menu popover anchors to a toolbar button, so collapsing the
 // toolbar out from under it would leave the menu floating, detached from it.
 const docksGroupPanel = useDocksGroupPanel()
+const docksOverflowPanel = useDocksOverflowPanel()
 
 const isCollapsed = computed(() => {
   if (!settings.value.autoCollapseEdgeToolbar)
@@ -70,7 +111,7 @@ const isCollapsed = computed(() => {
     return false
   if (context.panel.isDragging)
     return false
-  if (docksGroupPanel.value)
+  if (docksGroupPanel.value || docksOverflowPanel.value)
     return false
   if (hasPanelContent.value)
     return false
@@ -422,21 +463,46 @@ const dragPreviewStyle = computed<CSSProperties | undefined>(() => {
     <!-- Toolbar -->
     <div class="relative flex items-center shrink-0 select-none py1" :class="toolbarClass">
       <div
-        class="flex items-center flex-1 w-full transition-opacity duration-300"
+        class="flex items-center flex-1 min-w-0 min-h-0 w-full transition-opacity duration-300"
         :class="[isVertical ? 'flex-col' : 'flex-row', isCollapsed ? 'opacity-0 pointer-events-none' : 'opacity-100']"
       >
         <div
-          class="flex items-center flex-1 flex-wrap gap-0.5 px1"
-          :class="isVertical ? 'flex-col py1' : 'flex-row px1'"
+          ref="toolbarEntries"
+          class="flex items-center flex-1 min-w-0 min-h-0 gap-0.5 px1 [&>*]:shrink-0"
+          :class="isVertical ? 'flex-col py1 w-full' : 'flex-row'"
         >
           <DockEntriesWithCategories
             :context="context"
-            :groups="groupedEntries"
+            :groups="splitEntries.visible"
             :is-vertical="isVertical"
             :rotate="false"
             :selected="selectedEntry"
             @select="(e) => context.docks.switchEntry(e?.id)"
           />
+          <DockOverflowButton
+            v-if="splitEntries.overflow.length"
+            :context="context"
+            :groups="splitEntries.overflow"
+            :is-vertical="false"
+            :placement="positionDropdownPlacement[store.position]"
+            :selected="selectedEntry"
+            @select="(e) => context.docks.switchEntry(e?.id)"
+            @activity="bringUp"
+          />
+          <div
+            v-if="settingsEntries.length && groupedEntries.length"
+            class="border-base m1"
+            :class="isVertical ? 'w-20px h-px border-b-1.5' : 'h-20px w-px border-r-1.5'"
+          />
+          <div ref="settingsDock" class="shrink-0">
+            <DockEntries
+              :context="context"
+              :entries="settingsEntries"
+              :is-vertical="false"
+              :selected="selectedEntry"
+              @select="(e) => context.docks.switchEntry(e?.id)"
+            />
+          </div>
         </div>
 
         <!-- Position dropdown & float toggle -->

packages/hub-ui/src/client/components/dock/DockGroupButton.vue

@@ -2,7 +2,7 @@
 import type { DevframeDockEntry, DevframeViewGroup } from '@devframes/hub'
 import type { DocksContext } from '@devframes/hub/client'
 import { watchDebounced } from '@vueuse/core'
-import { computed, h, ref, useTemplateRef } from 'vue'
+import { computed, h, onBeforeUnmount, ref, useTemplateRef } from 'vue'
 import { getGroupMembers, getGroupMembersGrouped, resolveGroupPreferredChild } from '../../state/dock-settings'
 import { setDocksGroupPanel, useDocksGroupPanel } from '../../state/floating-tooltip'
 import { useSettings } from '../../state/settings-defaults'
@@ -75,6 +75,11 @@ function hidePanel() {
   setDocksGroupPanel(null)
 }
 
+onBeforeUnmount(() => {
+  if (docksGroupPanel.value?.el === groupButton.value)
+    hidePanel()
+})
+
 function togglePanel() {
   if (isPanelVisible.value)
     hidePanel()

packages/hub-ui/src/client/components/dock/DockOverflowButton.vue

@@ -2,8 +2,9 @@
 import type { DevframeDockEntry } from '@devframes/hub'
 import type { DocksContext } from '@devframes/hub/client'
 import type { DevframeDockEntriesGrouped } from '../../state/dock-settings'
+import type { FloatingPopoverProps } from '../../state/floating-tooltip'
 import { watchDebounced } from '@vueuse/core'
-import { computed, h, ref, useTemplateRef } from 'vue'
+import { computed, h, onBeforeUnmount, ref, useTemplateRef } from 'vue'
 import { setDocksOverflowPanel, useDocksOverflowPanel } from '../../state/floating-tooltip'
 import DockEntriesWithCategories from './DockEntriesWithCategories.vue'
 import DockEntry from './DockEntry.vue'
@@ -13,6 +14,7 @@ const props = defineProps<{
   isVertical: boolean
   groups: DevframeDockEntriesGrouped
   selected: DevframeDockEntry | null
+  placement?: FloatingPopoverProps['placement']
 }>()
 
 const emit = defineEmits<{
@@ -38,6 +40,15 @@ function showOverflowPanel() {
   setDocksOverflowPanel({
     content: () => h('div', {
       class: 'flex gap-0 flex-wrap max-w-220px',
+      // Edge menus also need room for the toolbar, popover padding and gap.
+      // Float mode keeps its existing sizing when no placement is supplied.
+      style: props.placement
+        ? {
+            maxWidth: `min(220px, calc(100vw - ${props.placement === 'left' || props.placement === 'right' ? 80 : 36}px))`,
+            maxHeight: `calc(100vh - ${props.placement === 'top' || props.placement === 'bottom' ? 80 : 36}px)`,
+            overflow: 'auto',
+          }
+        : undefined,
       onMousemove: () => emit('activity'),
     }, [
       h(DockEntriesWithCategories, {
@@ -52,6 +63,7 @@ function showOverflowPanel() {
       }),
     ]),
     el: overflowButton.value,
+    placement: props.placement,
   })
 }
 
@@ -75,6 +87,11 @@ function hideOverflowPanel() {
   isOverflowPanelVisible.value = false
   setDocksOverflowPanel(null)
 }
+
+onBeforeUnmount(() => {
+  if (docksOverflowPanel.value?.el === overflowButton.value)
+    hideOverflowPanel()
+})
 </script>
 
 <template>

packages/hub-ui/src/client/state/dock-settings.test.ts

@@ -1,7 +1,7 @@
 import type { DevframeDockEntriesGrouped, DevframeDockEntry, DevframeViewGroup } from '@devframes/hub'
 import type { WhenContext } from 'devframe/utils/when'
 import { describe, expect, it } from 'vitest'
-import { docksSplitGroupsWithCapacity, resolveGroupPreferredChild, resolveNextRecentDockId, resolveRecentDockEntry } from './dock-settings'
+import { docksSplitGroupsBySize, docksSplitGroupsWithCapacity, resolveGroupPreferredChild, resolveNextRecentDockId, resolveRecentDockEntry } from './dock-settings'
 
 function iframe(id: string, extra: Partial<DevframeDockEntry> = {}): DevframeDockEntry {
   return { id, type: 'iframe', url: '/', title: id.toUpperCase(), icon: 'ph:cube-duotone', ...extra } as DevframeDockEntry
@@ -23,6 +23,53 @@ function ids(groups: DevframeDockEntriesGrouped): string[] {
 const [a, b, c, d, e] = ['a', 'b', 'c', 'd', 'e'].map(id => iframe(id))
 const rail: DevframeDockEntriesGrouped = [['default', [a, b, c, d, e]]]
 
+describe('docksSplitGroupsBySize', () => {
+  const splitAt = (groups: DevframeDockEntriesGrouped, size: number) => docksSplitGroupsBySize(groups, size, 32, 2, 9.5)
+
+  it('restores every entry when the toolbar fits exactly, without reserving overflow', () => {
+    expect(ids(splitAt(rail, 168).visible)).toEqual(['a', 'b', 'c', 'd', 'e'])
+    expect(splitAt(rail, 168).overflow).toEqual([])
+    expect(ids(splitAt(rail, 167).overflow)).toEqual(['d', 'e'])
+  })
+
+  it('reserves the more button and preserves category order in a small toolbar', () => {
+    const groups: DevframeDockEntriesGrouped = [['first', [a, b]], ['second', [c, d, e]]]
+    const split = splitAt(groups, 145.5)
+    expect(split.visible).toEqual([['first', [a, b]], ['second', [c]]])
+    expect(split.overflow).toEqual([['second', [d, e]]])
+    expect(ids(splitAt(groups, 145).visible)).toEqual(['a', 'b'])
+  })
+
+  it('keeps a lone category overflow from folding back with an extra divider', () => {
+    const groups: DevframeDockEntriesGrouped = [['first', [a, b]], ['second', [c]]]
+    // Three icons fit (100px), but their category divider does not (111.5px).
+    const split = splitAt(groups, 100)
+    expect(ids(split.visible)).toEqual(['a', 'b'])
+    expect(ids(split.overflow)).toEqual(['c'])
+    expect(ids(splitAt(groups, 99.5).visible)).toEqual(['a'])
+    expect(ids(splitAt(groups, 111.5).visible)).toEqual(['a', 'b', 'c'])
+    expect(splitAt(groups, 111.5).overflow).toEqual([])
+  })
+
+  it('can put all entries in the menu when only the more button fits', () => {
+    const split = splitAt(rail, 32)
+    expect(split.visible).toEqual([])
+    expect(ids(split.overflow)).toEqual(['a', 'b', 'c', 'd', 'e'])
+  })
+
+  it('fits the rendered entries, dividers and menu across resize boundaries without losing entries', () => {
+    const groups: DevframeDockEntriesGrouped = [['first', [a, b]], ['second', [c]], ['third', [d, e]]]
+    for (let available = 32; available <= 200; available += 0.5) {
+      const split = splitAt(groups, available)
+      const buttons = ids(split.visible).length + Number(split.overflow.length > 0)
+      const dividers = Math.max(0, split.visible.length - 1)
+      const renderedSize = buttons * 32 + dividers * 9.5 + Math.max(0, buttons + dividers - 1) * 2
+      expect(renderedSize).toBeLessThanOrEqual(available)
+      expect([...ids(split.visible), ...ids(split.overflow)]).toEqual(['a', 'b', 'c', 'd', 'e'])
+    }
+  })
+})
+
 describe('docksSplitGroupsWithCapacity', () => {
   it('splits naturally without a recent entry', () => {
     const split = docksSplitGroupsWithCapacity(rail, 3)

packages/hub-ui/src/client/state/dock-settings.ts

@@ -523,6 +523,38 @@ export function docksSplitGroupsWithCapacity(
   return { visible: reduced.visible, overflow, recent: recentEntry }
 }
 
+/** Split an edge toolbar's entries using its available main-axis space. */
+export function docksSplitGroupsBySize(
+  groups: DevframeDockEntriesGrouped,
+  availableSize: number,
+  itemSize: number,
+  gap: number,
+  separatorSize: number,
+): SplitGroupsResult {
+  const total = groups.reduce((count, [, items]) => count + items.length, 0)
+  const separators = Math.max(0, groups.length - 1)
+  const fullSize = total * itemSize + separators * separatorSize + Math.max(0, total + separators - 1) * gap
+  if (fullSize <= availableSize)
+    return docksSplitGroupsWithCapacity(groups, total)
+
+  // Reserve the overflow button first. Each visible entry/divider adds its
+  // size plus a gap to the button or the next entry.
+  let remaining = availableSize - itemSize
+  let capacity = 0
+  for (const [index, [, items]] of groups.entries()) {
+    if (index > 0)
+      remaining -= separatorSize + gap
+    const count = Math.min(items.length, Math.max(0, Math.floor(remaining / (itemSize + gap))))
+    capacity += count
+    remaining -= count * (itemSize + gap)
+    if (count < items.length)
+      break
+  }
+  // Preserve a lone overflow entry: folding it inline can add a category
+  // divider that exceeds the measured space.
+  return { ...splitGroupsAt(groups, capacity), recent: null }
+}
+
 /**
  * Resolve a persisted recent-dock id (`DockSessionStorage.recentDockId`) to
  * the entry the float bar can raise, or `null` when the id no longer maps to a