From 43b8386ad8013eade798af45ea52e29b8e0ef67a Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Fri, 14 Aug 2026 11:48:57 +0000
Subject: [PATCH] fix(hub-ui,json-render-ui): FloatingPopover escapes a
 transformed ancestor's containing block; native Select mode
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`FloatingPopover` (hub-ui) is positioned `fixed` against its anchor's viewport rect, but a
`transform`/`filter`/`contain` ancestor makes itself the containing block for that
`position: fixed`, so the panel ends up positioned relative to — and clipped by — that
ancestor instead of the viewport. `resolveFixedEscapeTarget` walks up from the anchor to the
outermost such ancestor (escaping only the nearest one can land inside another) and
`<Teleport>`s the panel to its parent; walking `parentElement` stops at a shadow root's
boundary, so a dock's popover never escapes the shadow root its stylesheet is scoped to. With
no such ancestor, the panel renders in place as before.

`Select` (json-render-ui) gains `native`, rendering a real `<select>` instead of
`FormSelect`/`FormCombobox`: the browser draws its option list outside the page's layout, so
no ancestor can clip or reposition it at all — a dependable escape hatch for a `Select`
embedded in a host layout this component doesn't control, at the cost of `icon`,
`description` and `searchable`, which have no native equivalent.

Ports vitejs/devtools#518, adapted to this fork: that PR's `surface` prop and `Select`'s
switch to it don't have an equivalent here — this fork's `Select` renders through
@antfu/design's `FormSelect`/`FormCombobox` (reka-ui popovers), not through
`FloatingPopover`, so there's no consumer to point at a menu surface. (Those reka-ui
popovers default to portalling into `document.body`, which suffers the same class of bug
inside a shadow root or a transformed ancestor — worth a follow-up, but out of scope for a
first-party fix here.)

Closes #205

Co-authored-by: dvcolomban <dinh-van.colomban@contentsquare.com>
---
 .../floating/FloatingPopover.stories.ts       | 42 +++++++++++++++++++
 .../components/floating/FloatingPopover.ts    | 28 +++++++++----
 .../components/floating/floating-position.ts  | 25 +++++++++++
 .../json-render-ui/src/components/Select.ts   | 40 ++++++++++++++----
 packages/json-render/src/catalog.ts           |  2 +-
 packages/json-render/src/prop-schemas.ts      |  1 +
 packages/json-render/test/catalog.test.ts     |  4 ++
 .../json-render/index.snapshot.d.ts           |  2 +
 8 files changed, 129 insertions(+), 15 deletions(-)

diff --git a/packages/hub-ui/src/client/components/floating/FloatingPopover.stories.ts b/packages/hub-ui/src/client/components/floating/FloatingPopover.stories.ts
index e770fce1..8dd7f24e 100644
--- a/packages/hub-ui/src/client/components/floating/FloatingPopover.stories.ts
+++ b/packages/hub-ui/src/client/components/floating/FloatingPopover.stories.ts
@@ -93,6 +93,48 @@ export const ToggleTrigger: Story = {
   }),
 }
 
+/**
+ * A `transform` on an ancestor turns it into a containing block for `position: fixed`
+ * descendants — without the escape fix, the panel would be positioned relative to (and
+ * clipped by) the transformed box below rather than the viewport. It still lands on the
+ * trigger correctly here because `FloatingPopover` `<Teleport>`s the panel out to that
+ * ancestor's parent.
+ */
+export const EscapesTransformedAncestor: Story = {
+  render: () => defineComponent({
+    setup() {
+      const triggerEl = ref<HTMLElement | null>(null)
+      const open = ref(false)
+      const item = computed(() => (open.value && triggerEl.value)
+        ? { el: triggerEl.value, content: () => h('div', { class: 'flex flex-col gap-0.5 min-w-40' }, [
+            h('div', { class: 'px2 pt1 pb1.5 op60 text-2.75 uppercase tracking-wide font-medium' }, 'Menu'),
+            ...['Overview', 'Pages', 'Components'].map(label =>
+              h('button', { class: 'px2 py1.5 rounded text-sm text-left op80 hover:op100 hover:bg-active transition' }, label)),
+          ]) }
+        : null)
+      return () => h('div', { class: 'flex items-center justify-center p20 min-h-80 font-sans' }, [
+        h('div', {
+          class: 'p8 border-2 border-dashed border-red rounded of-hidden',
+          style: { transform: 'translateZ(0)' },
+        }, [
+          h('div', { class: 'text-xs op60 mb2' }, 'Transformed + clipping ancestor'),
+          h('button', {
+            ref: (el: any) => (triggerEl.value = el),
+            class: 'px3 py1.5 rounded border border-base bg-glass color-base shadow',
+            onClick: () => (open.value = !open.value),
+          }, 'Toggle menu'),
+        ]),
+        h(FloatingPopover, {
+          item: item.value,
+          panelClass: '!p0',
+          ignore: [triggerEl],
+          onDismiss: () => (open.value = false),
+        }),
+      ])
+    },
+  }),
+}
+
 export const CornerAnchors: Story = {
   render: () => defineComponent({
     setup() {
diff --git a/packages/hub-ui/src/client/components/floating/FloatingPopover.ts b/packages/hub-ui/src/client/components/floating/FloatingPopover.ts
index 5c1b63a2..79bc9074 100644
--- a/packages/hub-ui/src/client/components/floating/FloatingPopover.ts
+++ b/packages/hub-ui/src/client/components/floating/FloatingPopover.ts
@@ -2,8 +2,8 @@ import type { MaybeElementRef } from '@vueuse/core'
 import type { PropType, VNode } from 'vue'
 import type { FloatingPopoverProps } from '../../state/floating-tooltip'
 import { onClickOutside, useDebounceFn, useEventListener } from '@vueuse/core'
-import { defineComponent, h, nextTick, onMounted, onUpdated, reactive, ref, useTemplateRef, watch } from 'vue'
-import { resolveFloatingPosition } from './floating-position'
+import { defineComponent, h, nextTick, onMounted, onUpdated, reactive, ref, Teleport, useTemplateRef, watch } from 'vue'
+import { resolveFixedEscapeTarget, resolveFloatingPosition } from './floating-position'
 
 // @unocss-include
 
@@ -34,6 +34,12 @@ const FloatingPopoverComponent = defineComponent({
     const panel = useTemplateRef<HTMLDivElement>('panel')
     const el = ref(props.item?.el)
     const renderCounter = ref(0)
+    /** Resolved from the anchor rather than the panel, which may not be in the document yet. */
+    const escapeTarget = ref<HTMLElement | undefined>()
+
+    function refreshEscapeTarget(anchor: Element | undefined) {
+      escapeTarget.value = anchor ? resolveFixedEscapeTarget(anchor) : undefined
+    }
 
     const panelSize = reactive({ width: 0, height: 0 })
     // Before the first measurement, `resolveFloatingPosition` centers the panel
@@ -59,7 +65,10 @@ const FloatingPopoverComponent = defineComponent({
       })
     }
 
-    onMounted(measurePanel)
+    onMounted(() => {
+      refreshEscapeTarget(props.item?.el)
+      measurePanel()
+    })
     onUpdated(measurePanel)
 
     useEventListener(window, 'resize', () => {
@@ -97,6 +106,7 @@ const FloatingPopoverComponent = defineComponent({
             el.value = value.el
           else
             renderCounter.value++
+          refreshEscapeTarget(value.el)
         }
         else {
           clearThrottled()
@@ -107,6 +117,10 @@ const FloatingPopoverComponent = defineComponent({
     let previousContent: VNode | undefined
     let previousStyle: Record<string, string> = {}
 
+    /** Escapes the anchor's containing block when there is one, otherwise renders in place. */
+    const withEscape = (node: VNode) =>
+      escapeTarget.value ? h(Teleport, { to: escapeTarget.value }, [node]) : node
+
     return () => {
       // Force re-render to update the position
       // eslint-disable-next-line ts/no-unused-expressions
@@ -120,7 +134,7 @@ const FloatingPopoverComponent = defineComponent({
       // When dismissing (item is null), keep the last known position
       // so the popover fades out in place instead of jumping
       if (!props.item) {
-        return h(
+        return withEscape(h(
           'div',
           {
             ref: 'panel',
@@ -132,7 +146,7 @@ const FloatingPopoverComponent = defineComponent({
             style: previousStyle,
           },
           previousContent,
-        )
+        ))
       }
 
       const rect = el.value.getBoundingClientRect()
@@ -157,7 +171,7 @@ const FloatingPopoverComponent = defineComponent({
 
       previousContent = content
 
-      return h(
+      return withEscape(h(
         'div',
         {
           ref: 'panel',
@@ -169,7 +183,7 @@ const FloatingPopoverComponent = defineComponent({
           style,
         },
         content,
-      )
+      ))
     }
   },
 })
diff --git a/packages/hub-ui/src/client/components/floating/floating-position.ts b/packages/hub-ui/src/client/components/floating/floating-position.ts
index 9fad0329..38dcc7b3 100644
--- a/packages/hub-ui/src/client/components/floating/floating-position.ts
+++ b/packages/hub-ui/src/client/components/floating/floating-position.ts
@@ -100,3 +100,28 @@ export function resolveFloatingPosition(options: ResolveFloatingPositionOptions)
 
   return { align, style }
 }
+
+/** Properties whose computed value, when not `none`, makes an element a containing block for `position: fixed` descendants. */
+const FIXED_CONTAINING_BLOCK_PROPERTIES = ['transform', 'translate', 'rotate', 'scale', 'perspective', 'filter', 'backdropFilter'] as const
+
+/**
+ * The element a fixed-position panel anchored to `anchor` must be `<Teleport>`ed into to
+ * avoid being positioned relative to — and clipped by — a transformed ancestor, or
+ * `undefined` when there is no such ancestor and the panel can stay in place.
+ *
+ * Returns the *outermost* offending ancestor's parent: escaping only the nearest one can
+ * land inside another, leaving the panel just as mispositioned. Walking `parentElement`
+ * (rather than `parentNode`) naturally stops at a shadow root's boundary — a dock's popover
+ * never escapes the shadow root that its stylesheet is scoped to.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/CSS/position#fixed
+ */
+export function resolveFixedEscapeTarget(anchor: Element): HTMLElement | undefined {
+  let outermost: HTMLElement | undefined
+  for (let node = anchor.parentElement; node; node = node.parentElement) {
+    const style = getComputedStyle(node)
+    if (FIXED_CONTAINING_BLOCK_PROPERTIES.some(property => style[property] !== 'none') || /paint|layout|strict|content/.test(style.contain))
+      outermost = node
+  }
+  return outermost?.parentElement ?? undefined
+}
diff --git a/packages/json-render-ui/src/components/Select.ts b/packages/json-render-ui/src/components/Select.ts
index 15bcb68b..74b3c7e4 100644
--- a/packages/json-render-ui/src/components/Select.ts
+++ b/packages/json-render-ui/src/components/Select.ts
@@ -21,6 +21,13 @@ interface SelectProps {
   disabled?: boolean
   /** Swap the plain select for a searchable combobox. */
   searchable?: boolean
+  /**
+   * Renders a real `<select>` instead of `FormSelect`/`FormCombobox`. The browser draws its
+   * option list outside the page's layout, so no ancestor can clip or reposition it — the
+   * dependable choice for a `Select` embedded in a host layout this component doesn't
+   * control. Takes priority over `searchable`, which has no native equivalent.
+   */
+  native?: boolean
 }
 
 function normalize(option: string | SelectOption): { value: string, label?: string } {
@@ -39,6 +46,7 @@ const SelectImpl = defineComponent({
     label: { type: String, default: undefined },
     disabled: { type: Boolean, default: undefined },
     searchable: { type: Boolean, default: undefined },
+    native: { type: Boolean, default: undefined },
     bindingPath: { type: String, default: undefined },
     onChange: { type: Function as PropType<() => void>, default: undefined },
   },
@@ -56,7 +64,30 @@ const SelectImpl = defineComponent({
       props.onChange?.()
     }
     const options = computed(() => props.options.map(normalize))
+    const withLabel = (control: ReturnType<typeof h>) => {
+      if (!props.label)
+        return control
+      return h('div', { class: 'flex flex-col gap-1' }, [
+        h('label', { class: 'text-sm font-medium' }, props.label),
+        control,
+      ])
+    }
     return () => {
+      if (props.native) {
+        return withLabel(h('select', {
+          'value': model.value ?? '',
+          'disabled': props.disabled,
+          'aria-label': props.label,
+          'class': 'text-sm px2.5 h-9 min-w-40 border border-base rounded bg-base color-base outline-none transition disabled:op50 disabled:pointer-events-none focus-visible:ring-2 focus-visible:ring-primary-500/40',
+          'onChange': (e: Event) => setModel((e.target as HTMLSelectElement).value),
+        }, [
+          // Only while unset, so the placeholder can't be re-selected afterwards.
+          props.placeholder && model.value === undefined
+            ? h('option', { value: '', disabled: true }, props.placeholder)
+            : null,
+          ...options.value.map(option => h('option', { value: option.value }, option.label ?? option.value)),
+        ]))
+      }
       const Comp = (props.searchable ? FormCombobox : FormSelect) as unknown as Parameters<typeof h>[0]
       const control = h(Comp, {
         'options': options.value,
@@ -65,13 +96,7 @@ const SelectImpl = defineComponent({
         'modelValue': model.value,
         'onUpdate:modelValue': (next: string) => setModel(next),
       })
-      if (props.label) {
-        return h('div', { class: 'flex flex-col gap-1' }, [
-          h('label', { class: 'text-sm font-medium' }, props.label),
-          control,
-        ])
-      }
-      return control
+      return withLabel(control)
     }
   },
 })
@@ -84,6 +109,7 @@ export const Select: JrComponent<SelectProps> = ({ props, on, bindings }) =>
     label: props.label,
     disabled: props.disabled,
     searchable: props.searchable,
+    native: props.native,
     bindingPath: bindings?.value,
     onChange: () => on('change').emit(),
   })
diff --git a/packages/json-render/src/catalog.ts b/packages/json-render/src/catalog.ts
index d8f280c9..4143c824 100644
--- a/packages/json-render/src/catalog.ts
+++ b/packages/json-render/src/catalog.ts
@@ -45,7 +45,7 @@ const componentDescriptions: Record<keyof typeof basePropSchemas, string> = {
   Tree: 'Recursive object/array viewer with expandable nodes.',
   Tabs: 'Tabbed container; each child renders under the positionally-matching tab.',
   Link: 'Hyperlink to a safe-scheme URL with an optional icon.',
-  Select: 'Single-select dropdown bound to a state value, with optional search.',
+  Select: 'Single-select dropdown bound to a state value, with optional search or a native `<select>` fallback.',
 }
 
 /**
diff --git a/packages/json-render/src/prop-schemas.ts b/packages/json-render/src/prop-schemas.ts
index 8fd4a26f..76d27434 100644
--- a/packages/json-render/src/prop-schemas.ts
+++ b/packages/json-render/src/prop-schemas.ts
@@ -160,6 +160,7 @@ export const SelectPropsSchema = z.object({
   label: str.optional(),
   disabled: bool.optional(),
   searchable: bool.optional(),
+  native: bool.optional(),
 })
 
 /**
diff --git a/packages/json-render/test/catalog.test.ts b/packages/json-render/test/catalog.test.ts
index b487d5a0..6b828551 100644
--- a/packages/json-render/test/catalog.test.ts
+++ b/packages/json-render/test/catalog.test.ts
@@ -40,6 +40,10 @@ describe('per-component prop validation', () => {
     expect(basePropSchemas.Progress.safeParse({ value: 40, max: 100 }).success).toBe(true)
   })
 
+  it('accepts Select.native alongside the rest of its props', () => {
+    expect(basePropSchemas.Select.safeParse({ options: ['a', 'b'], native: true }).success).toBe(true)
+  })
+
   it('rejects an out-of-set enum value', () => {
     expect(basePropSchemas.Button.safeParse({ variant: 'nope' }).success).toBe(false)
     expect(basePropSchemas.Badge.safeParse({ variant: 'purple' }).success).toBe(false)
diff --git a/tests/__snapshots__/tsnapi/@devframes/json-render/index.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/json-render/index.snapshot.d.ts
index ec8e12bc..a77e49f2 100644
--- a/tests/__snapshots__/tsnapi/@devframes/json-render/index.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/json-render/index.snapshot.d.ts
@@ -241,6 +241,7 @@ export declare const basePropSchemas: {
     label: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodIntersection<z.ZodObject<{}, z.core.$loose>, z.ZodRecord<z.ZodString, z.ZodUnknown>>]>>;
     disabled: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodIntersection<z.ZodObject<{}, z.core.$loose>, z.ZodRecord<z.ZodString, z.ZodUnknown>>]>>;
     searchable: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodIntersection<z.ZodObject<{}, z.core.$loose>, z.ZodRecord<z.ZodString, z.ZodUnknown>>]>>;
+    native: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodIntersection<z.ZodObject<{}, z.core.$loose>, z.ZodRecord<z.ZodString, z.ZodUnknown>>]>>;
   }, z.core.$strip>;
 };
 export declare const baseSchema: import("@json-render/core").Schema<{
@@ -331,6 +332,7 @@ export declare const SelectPropsSchema: z.ZodObject<{
   label: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodIntersection<z.ZodObject<{}, z.core.$loose>, z.ZodRecord<z.ZodString, z.ZodUnknown>>]>>;
   disabled: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodIntersection<z.ZodObject<{}, z.core.$loose>, z.ZodRecord<z.ZodString, z.ZodUnknown>>]>>;
   searchable: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodIntersection<z.ZodObject<{}, z.core.$loose>, z.ZodRecord<z.ZodString, z.ZodUnknown>>]>>;
+  native: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodIntersection<z.ZodObject<{}, z.core.$loose>, z.ZodRecord<z.ZodString, z.ZodUnknown>>]>>;
 }, z.core.$strip>;
 export declare const StackPropsSchema: z.ZodObject<{
   direction: z.ZodOptional<z.ZodEnum<{