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

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