@nexxtmove/ui 2.6.0 → 2.8.0

package/src/components/atoms/FloatingPanel/FloatingPanel.stories.ts

@@ -0,0 +1,677 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite'
+import { expect, screen, userEvent, waitFor, within } from 'storybook/test'
+import { ref, onMounted } from 'vue'
+import FloatingPanel from './FloatingPanel.vue'
+import NexxtButton from '../Button/Button.vue'
+import NexxtModal from '../../organisms/Modal/Modal.vue'
+
+export default {
+  title: 'Components/Atoms/Floating Panel',
+  component: FloatingPanel,
+  decorators: [
+    () => ({
+      // Room for an open panel above or below a centred trigger, also inline on the Docs page.
+      template:
+        '<div style="min-height: 400px; padding: 48px; display: flex; align-items: center; justify-content: center;"><story /></div>',
+    }),
+  ],
+  argTypes: {
+    placement: {
+      control: 'select',
+      options: [
+        'bottom-start',
+        'bottom',
+        'bottom-end',
+        'top-start',
+        'top',
+        'top-end',
+        'left-start',
+        'left',
+        'left-end',
+        'right-start',
+        'right',
+        'right-end',
+      ],
+    },
+    offsetDistance: { control: 'number' },
+  },
+} satisfies Meta<typeof FloatingPanel>
+
+type Story = StoryObj<typeof FloatingPanel>
+
+/**
+ * The panel scales and fades in from its trigger. Under `prefers-reduced-motion: reduce` it
+ * appears and disappears without animation; to see that here, use DevTools → Rendering →
+ * "Emulate CSS media feature prefers-reduced-motion".
+ */
+export const Default: Story = {
+  render: (args) => ({
+    components: { FloatingPanel, NexxtButton },
+    setup() {
+      return { args }
+    },
+    template: `
+      <FloatingPanel v-bind="args">
+        <template #trigger="{ isOpen, toggle }">
+          <NexxtButton variant="secondary" :aria-expanded="isOpen" @click="toggle">
+            {{ isOpen ? 'Close' : 'Open panel' }}
+          </NexxtButton>
+        </template>
+        <template #content>
+          <div style="background: white; border: 1px solid #e5e7eb; border-radius: 8px; padding: 16px; box-shadow: 0 4px 12px rgba(0,0,0,0.1); min-width: 200px;">
+            <p style="margin: 0; font-size: 14px; color: #374151;">Floating panel content</p>
+          </div>
+        </template>
+      </FloatingPanel>
+    `,
+  }),
+  args: {
+    placement: 'bottom-start',
+  },
+}
+
+export const AllPlacements: Story = {
+  render: () => ({
+    components: { FloatingPanel, NexxtButton },
+    setup() {
+      const placements = [
+        'bottom-start',
+        'bottom',
+        'bottom-end',
+        'top-start',
+        'top',
+        'top-end',
+        'right-start',
+        'right',
+        'left-start',
+        'left',
+      ] as const
+      return { placements }
+    },
+    template: `
+      <div style="display: flex; flex-wrap: wrap; justify-content: center; gap: 8px; max-width: 560px;">
+        <FloatingPanel v-for="p in placements" :key="p" :placement="p">
+          <template #trigger="{ toggle, isOpen }">
+            <NexxtButton variant="secondary" :aria-expanded="isOpen" @click="toggle">
+              {{ p }}
+            </NexxtButton>
+          </template>
+          <template #content>
+            <div style="background: white; border: 1px solid #e5e7eb; border-radius: 8px; padding: 12px; box-shadow: 0 4px 12px rgba(0,0,0,0.1); font-size: 13px; color: #374151;">
+              Placed: {{ p }}
+            </div>
+          </template>
+        </FloatingPanel>
+      </div>
+    `,
+  }),
+}
+
+export const InsideOverflowHidden: Story = {
+  decorators: [
+    () => ({
+      // The panel is meant to stick out of the dashed box; the padding keeps it inside the story.
+      template: `
+        <div style="padding-bottom: 160px;">
+          <div style="overflow: hidden; border: 2px dashed #f87171; border-radius: 8px; padding: 32px; display: flex; align-items: center; justify-content: center; min-height: 200px;">
+            <p style="position: absolute; top: 8px; left: 12px; font-size: 11px; color: #f87171; margin: 0;">overflow: hidden container: panel escapes via position: fixed</p>
+            <story />
+          </div>
+        </div>
+      `,
+    }),
+  ],
+  render: (args) => ({
+    components: { FloatingPanel, NexxtButton },
+    setup() {
+      return { args }
+    },
+    template: `
+      <FloatingPanel v-bind="args">
+        <template #trigger="{ toggle, isOpen }">
+          <NexxtButton variant="secondary" :aria-expanded="isOpen" @click="toggle">
+            Open (escapes overflow)
+          </NexxtButton>
+        </template>
+        <template #content>
+          <div style="background: white; border: 1px solid #e5e7eb; border-radius: 8px; padding: 20px; box-shadow: 0 4px 12px rgba(0,0,0,0.1); max-width: 280px;">
+            <p style="margin: 0 0 8px; font-size: 14px; font-weight: 600; color: #111827;">Escaped via position: fixed</p>
+            <p style="margin: 0 0 12px; font-size: 13px; color: #6b7280;">This panel is rendered next to its trigger, but <code>position: fixed</code> takes it out of the container's clipping.</p>
+            <p style="margin: 0; font-size: 13px; color: #6b7280;">Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt.</p>
+          </div>
+        </template>
+      </FloatingPanel>
+    `,
+  }),
+  args: {
+    placement: 'bottom-start',
+  },
+}
+
+export const WithInputFocus: Story = {
+  render: (args) => ({
+    components: { FloatingPanel },
+    setup() {
+      return { args }
+    },
+    template: `
+      <FloatingPanel v-bind="args">
+        <template #trigger="{ isOpen, open }">
+          <input
+            type="text"
+            placeholder="Focus me to open the panel"
+            :aria-expanded="isOpen"
+            @focus="open"
+            style="border: 1px solid #d1d5db; border-radius: 6px; padding: 8px 12px; font-size: 14px; outline: none; width: 240px; box-sizing: border-box;"
+          />
+        </template>
+        <template #content>
+          <div style="background: white; border: 1px solid #e5e7eb; border-radius: 8px; padding: 16px; box-shadow: 0 4px 12px rgba(0,0,0,0.1); min-width: 240px;">
+            <p style="margin: 0 0 8px; font-size: 14px; font-weight: 600; color: #111827;">Suggestions</p>
+            <ul style="margin: 0; padding: 0; list-style: none; display: flex; flex-direction: column; gap: 4px;">
+              <li style="font-size: 14px; color: #374151; padding: 6px 8px; border-radius: 4px; cursor: pointer; background: #f9fafb;">Option A</li>
+              <li style="font-size: 14px; color: #374151; padding: 6px 8px; border-radius: 4px; cursor: pointer;">Option B</li>
+              <li style="font-size: 14px; color: #374151; padding: 6px 8px; border-radius: 4px; cursor: pointer;">Option C</li>
+            </ul>
+          </div>
+        </template>
+      </FloatingPanel>
+    `,
+  }),
+  args: {
+    placement: 'bottom-start',
+  },
+}
+
+export const WithCloseSlotProp: Story = {
+  render: (args) => ({
+    components: { FloatingPanel, NexxtButton },
+    setup() {
+      const log = ref<string[]>([])
+      return { args, log }
+    },
+    template: `
+      <div style="display: flex; flex-direction: column; align-items: center; gap: 12px;">
+        <FloatingPanel v-bind="args" @open="log.push('opened')" @close="log.push('closed')">
+          <template #trigger="{ toggle, isOpen }">
+            <NexxtButton variant="secondary" :aria-expanded="isOpen" @click="toggle">
+              Toggle
+            </NexxtButton>
+          </template>
+          <template #content="{ close }">
+            <div style="background: white; border: 1px solid #e5e7eb; border-radius: 8px; padding: 16px; box-shadow: 0 4px 12px rgba(0,0,0,0.1); display: flex; flex-direction: column; gap: 8px; min-width: 180px;">
+              <p style="margin: 0; font-size: 14px; color: #374151;">Panel is open</p>
+              <NexxtButton variant="danger" @click="close">Close from inside</NexxtButton>
+            </div>
+          </template>
+        </FloatingPanel>
+        <ul style="font-size: 12px; color: #6b7280; list-style: none; padding: 0; margin: 0;">
+          <li v-for="(entry, i) in log" :key="i">{{ entry }}</li>
+        </ul>
+      </div>
+    `,
+  }),
+  args: {
+    placement: 'bottom-start',
+  },
+}
+
+/**
+ * `surface` (default `false`) wraps the content slot in the standard panel surface
+ * — rounded corners, a light border, a white background and a small shadow — so a
+ * consumer no longer has to hand-roll one per call site.
+ *
+ * Both panels below render the exact same unstyled content slot. The left one is
+ * the bare default: with nothing behind it, the content sits directly on the page.
+ * The right one has `surface` on. Both open on mount so the difference is visible
+ * without interacting.
+ */
+export const Surface: Story = {
+  render: () => ({
+    components: { FloatingPanel, NexxtButton },
+    setup() {
+      const bare = ref<InstanceType<typeof FloatingPanel> | null>(null)
+      const surfaced = ref<InstanceType<typeof FloatingPanel> | null>(null)
+      onMounted(() => {
+        bare.value?.open()
+        surfaced.value?.open()
+      })
+      return { bare, surfaced }
+    },
+    template: `
+      <div style="display: flex; gap: 160px; align-items: flex-start;">
+        <div style="display: flex; flex-direction: column; align-items: center; gap: 8px;">
+          <span style="font-size: 11px; text-transform: uppercase; letter-spacing: 0.05em; color: #374151;">surface: false (default)</span>
+          <FloatingPanel ref="bare" placement="bottom">
+            <template #trigger="{ toggle, isOpen }">
+              <NexxtButton variant="secondary" :aria-expanded="isOpen" @click="toggle">Bare</NexxtButton>
+            </template>
+            <template #content>
+              <div style="width: 180px;">
+                <p style="margin: 0 0 4px; font-weight: 600;">Unstyled content</p>
+                <p style="margin: 0;">No wrapper — the slot is placed as-is.</p>
+              </div>
+            </template>
+          </FloatingPanel>
+        </div>
+
+        <div style="display: flex; flex-direction: column; align-items: center; gap: 8px;">
+          <span style="font-size: 11px; text-transform: uppercase; letter-spacing: 0.05em; color: #374151;">surface: true</span>
+          <FloatingPanel ref="surfaced" placement="bottom" surface>
+            <template #trigger="{ toggle, isOpen }">
+              <NexxtButton variant="secondary" :aria-expanded="isOpen" @click="toggle">Surface</NexxtButton>
+            </template>
+            <template #content>
+              <div style="width: 180px;">
+                <p style="margin: 0 0 4px; font-weight: 600;">Unstyled content</p>
+                <p style="margin: 0;">Same slot, wrapped by the component.</p>
+              </div>
+            </template>
+          </FloatingPanel>
+        </div>
+      </div>
+    `,
+  }),
+}
+
+/**
+ * `surface` on its own, opened by hand — the everyday case a consumer writes now
+ * that the panel supplies its own background.
+ */
+export const SurfaceInteractive: Story = {
+  render: (args) => ({
+    components: { FloatingPanel, NexxtButton },
+    setup() {
+      return { args }
+    },
+    template: `
+      <FloatingPanel v-bind="args" surface>
+        <template #trigger="{ isOpen, toggle }">
+          <NexxtButton variant="secondary" :aria-expanded="isOpen" @click="toggle">
+            {{ isOpen ? 'Close' : 'Open panel' }}
+          </NexxtButton>
+        </template>
+        <template #content>
+          <div style="padding: 16px; min-width: 220px; max-width: 280px;">
+            <p style="margin: 0 0 8px; font-weight: 600;">Surface panel</p>
+            <p style="margin: 0;">The border, radius, white background and shadow come from the component.</p>
+          </div>
+        </template>
+      </FloatingPanel>
+    `,
+  }),
+  args: {
+    placement: 'bottom-start',
+  },
+}
+
+/**
+ * `surface` over busy page content, which is the case it exists for: the panel has
+ * to stay legible when something is scrolling underneath it. The bare default is
+ * shown over the same content for comparison.
+ */
+export const SurfaceOverContent: Story = {
+  render: () => ({
+    components: { FloatingPanel, NexxtButton },
+    setup() {
+      const bare = ref<InstanceType<typeof FloatingPanel> | null>(null)
+      const surfaced = ref<InstanceType<typeof FloatingPanel> | null>(null)
+      onMounted(() => {
+        bare.value?.open()
+        surfaced.value?.open()
+      })
+      return { bare, surfaced }
+    },
+    template: `
+      <div style="position: relative; width: 620px;">
+        <p style="position: absolute; inset: 60px 0 auto 0; margin: 0; font-size: 13px; line-height: 22px; color: #4b5563;">
+          Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+          incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
+          nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+          Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore.
+        </p>
+        <div style="display: flex; gap: 200px; position: relative;">
+          <FloatingPanel ref="bare" placement="bottom">
+            <template #trigger="{ toggle, isOpen }">
+              <NexxtButton variant="secondary" :aria-expanded="isOpen" @click="toggle">Bare</NexxtButton>
+            </template>
+            <template #content>
+              <div style="width: 170px;">Content with nothing behind it.</div>
+            </template>
+          </FloatingPanel>
+
+          <FloatingPanel ref="surfaced" placement="bottom" surface>
+            <template #trigger="{ toggle, isOpen }">
+              <NexxtButton variant="secondary" :aria-expanded="isOpen" @click="toggle">Surface</NexxtButton>
+            </template>
+            <template #content>
+              <div style="width: 170px; padding: 12px;">Content on its own surface.</div>
+            </template>
+          </FloatingPanel>
+        </div>
+      </div>
+    `,
+  }),
+}
+
+/**
+ * `surface="raised"` is the surface for large panels that cover a stretch of white page or
+ * canvas, such as a picker: a gray-300 border and `shadow-lg`, so the panel reads as a layer
+ * above the page. `surface` (`true`) stays the surface for dropdowns, selects, menus and
+ * suggestions. Rule of thumb: if the panel covers content the user was just looking at, raise it.
+ */
+export const Raised: Story = {
+  render: () => ({
+    components: { FloatingPanel, NexxtButton },
+    setup() {
+      const standard = ref<InstanceType<typeof FloatingPanel> | null>(null)
+      const raised = ref<InstanceType<typeof FloatingPanel> | null>(null)
+      onMounted(() => {
+        standard.value?.open()
+        raised.value?.open()
+      })
+      return { standard, raised }
+    },
+    template: `
+      <div style="position: relative; width: 100%; background: white; display: grid; grid-template-columns: repeat(auto-fit, 482px); justify-content: center; column-gap: 48px;">
+        <div aria-hidden="true" style="position: absolute; inset: 48px 0 0 0; overflow: hidden; font-size: 13px; line-height: 22px; color: #4b5563;">
+          <p v-for="n in 8" :key="n" style="margin: 0 0 8px;">
+            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+            incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud
+            exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure
+            dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.
+            Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt.
+          </p>
+        </div>
+        <div style="min-height: 340px;">
+          <FloatingPanel ref="standard" placement="bottom-start" surface>
+            <template #trigger="{ toggle, isOpen }">
+              <NexxtButton variant="secondary" :aria-expanded="isOpen" @click="toggle">surface</NexxtButton>
+            </template>
+            <template #content>
+              <div data-testid="content-surface" style="width: 480px; height: 280px; padding: 16px;">
+                Small-panel surface over a large area.
+              </div>
+            </template>
+          </FloatingPanel>
+        </div>
+        <div style="min-height: 340px;">
+          <FloatingPanel ref="raised" placement="bottom-start" surface="raised">
+            <template #trigger="{ toggle, isOpen }">
+              <NexxtButton variant="secondary" :aria-expanded="isOpen" @click="toggle">surface="raised"</NexxtButton>
+            </template>
+            <template #content>
+              <div data-testid="content-raised" style="width: 480px; height: 280px; padding: 16px;">
+                Raised surface: reads as a layer above the page.
+              </div>
+            </template>
+          </FloatingPanel>
+        </div>
+      </div>
+    `,
+  }),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+    const standard = (await canvas.findByTestId('content-surface')).parentElement!
+    const raised = (await canvas.findByTestId('content-raised')).parentElement!
+
+    // Resolve the token through an inline style, so the expected value does not depend on the
+    // same Tailwind scan that produced the classes under test.
+    const probe = document.createElement('div')
+    probe.style.color = 'var(--color-gray-300)'
+    document.body.append(probe)
+    const gray300 = getComputedStyle(probe).color
+    probe.remove()
+    await expect(
+      getComputedStyle(document.documentElement).getPropertyValue('--color-gray-300').trim(),
+    ).not.toBe('')
+
+    await expect(getComputedStyle(raised).borderTopColor).toBe(gray300)
+    await expect(getComputedStyle(raised).boxShadow).not.toBe('none')
+    await expect(getComputedStyle(raised).boxShadow).not.toBe(getComputedStyle(standard).boxShadow)
+    await expect(getComputedStyle(standard).borderTopColor).not.toBe(gray300)
+  },
+}
+
+/**
+ * `fitHeight` hands the content the room on the roomiest side of the trigger, as the
+ * `availableHeight` slot prop and as `--floating-panel-available-height`. The panel sets no
+ * height itself; the content decides. Here the trigger sits at the bottom of the viewport, so the
+ * list is capped to the room above it and the panel flips up.
+ */
+export const FitHeight: Story = {
+  parameters: { layout: 'fullscreen' },
+  decorators: [
+    () => ({
+      // The meta decorator adds 48px padding on each side; together they fill the viewport.
+      template:
+        '<div style="height: calc(100dvh - 96px); display: flex; align-items: end;"><story /></div>',
+    }),
+  ],
+  render: () => ({
+    components: { FloatingPanel, NexxtButton },
+    setup() {
+      const rows = Array.from({ length: 60 }, (_, i) => `Row ${i + 1}`)
+      return { rows }
+    },
+    template: `
+      <FloatingPanel placement="bottom-start" surface fit-height>
+        <template #trigger="{ toggle, isOpen }">
+          <NexxtButton variant="secondary" :aria-expanded="isOpen" @click="toggle">Open long list</NexxtButton>
+        </template>
+        <template #content="{ availableHeight }">
+          <ul
+            data-testid="fit-list"
+            :data-available-height="availableHeight"
+            :style="{ maxHeight: availableHeight + 'px' }"
+            class="overflow-y-auto"
+            style="margin: 0; padding: 8px 16px; list-style: none; width: 220px;"
+          >
+            <li v-for="row in rows" :key="row" style="padding: 4px 0;">{{ row }}</li>
+          </ul>
+        </template>
+      </FloatingPanel>
+    `,
+  }),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+    const trigger = canvas.getByRole('button', { name: 'Open long list' })
+    await userEvent.click(trigger)
+    const list = await canvas.findByTestId('fit-list')
+
+    const triggerRect = trigger.getBoundingClientRect()
+    const viewport = document.documentElement.clientHeight
+    const expected =
+      Math.floor(Math.max(triggerRect.top, viewport - triggerRect.bottom)) - 8 - 8 - 2
+    await expect(Number(list.dataset.availableHeight)).toBe(expected)
+
+    // Measure the positioning element, which is never transformed by the enter transition.
+    const panel = list.closest('.z-50')!
+    await waitFor(() => {
+      const rect = panel.getBoundingClientRect()
+      // the list uses all the room it gets: 8px from the edge, less than a pixel of rounding
+      expect(rect.top).toBeGreaterThanOrEqual(8)
+      expect(rect.top).toBeLessThan(9)
+      expect(rect.bottom).toBeLessThanOrEqual(triggerRect.top)
+    })
+  },
+}
+
+/**
+ * Two sibling wrappers with the same `z-index`: the first holds the trigger, the second overlaps
+ * the area where the panel opens. Left, without `teleport`, the panel lives in the first
+ * wrapper's stacking context, so the later sibling paints over it. Right, with `teleport`, the
+ * panel renders at the end of `<body>` and stays on top.
+ */
+export const StackingContext: Story = {
+  render: () => ({
+    components: { FloatingPanel, NexxtButton },
+    setup() {
+      // `ref` inside v-for collects every instance into this array
+      const panels = ref<InstanceType<typeof FloatingPanel>[]>([])
+      onMounted(() => panels.value.forEach((panel) => panel.open()))
+      const columns = [
+        { key: 'in-place', label: 'teleport: false', teleport: false },
+        { key: 'teleported', label: 'teleport: true', teleport: true },
+      ]
+      return { panels, columns }
+    },
+    template: `
+      <div style="display: flex; gap: 32px; align-items: flex-start;">
+        <div v-for="column in columns" :key="column.key" :data-column="column.key" style="width: 180px;">
+          <p style="margin: 0 0 8px; font-size: 11px; text-transform: uppercase; letter-spacing: 0.05em; color: #374151;">{{ column.label }}</p>
+          <div class="relative z-10">
+            <FloatingPanel ref="panels" :teleport="column.teleport" surface>
+              <template #trigger="{ toggle, isOpen }">
+                <NexxtButton variant="secondary" :aria-expanded="isOpen" @click="toggle">Open</NexxtButton>
+              </template>
+              <template #content>
+                <div :data-testid="'stack-panel-' + column.key" style="width: 160px; height: 96px; padding: 12px;">Panel</div>
+              </template>
+            </FloatingPanel>
+          </div>
+          <div data-sibling class="relative z-10" style="margin-top: 24px; height: 120px; background: #fde68a; border-radius: 8px; padding: 8px; font-size: 12px; color: #1f2937;">
+            Sibling, same z-index
+          </div>
+        </div>
+      </div>
+    `,
+  }),
+  play: async ({ canvasElement }) => {
+    const topAt = async (key: string) => {
+      const column = canvasElement.querySelector(`[data-column="${key}"]`)!
+      const sibling = column.querySelector('[data-sibling]')!
+      // Teleported content is outside canvasElement, so search the whole document.
+      const panel = await within(document.body).findByTestId(`stack-panel-${key}`)
+      // Wait for the enter transition: during the scale-in the rect is still growing.
+      await new Promise((resolve) => setTimeout(resolve, 300))
+      const a = panel.getBoundingClientRect()
+      const b = sibling.getBoundingClientRect()
+      const x = (Math.max(a.left, b.left) + Math.min(a.right, b.right)) / 2
+      const y = (Math.max(a.top, b.top) + Math.min(a.bottom, b.bottom)) / 2
+      await expect(Math.min(a.bottom, b.bottom)).toBeGreaterThan(Math.max(a.top, b.top))
+      return { hit: document.elementFromPoint(x, y), panel }
+    }
+
+    const left = await topAt('in-place')
+    await expect(left.hit?.closest('[data-sibling]')).not.toBeNull()
+
+    const right = await topAt('teleported')
+    await expect(right.panel.contains(right.hit)).toBe(true)
+  },
+}
+
+/**
+ * With `teleport`, the panel sits at the end of `<body>`, yet Tab and Shift+Tab walk the page as
+ * if it still followed the trigger: three invisible focus guards hand focus on. Tab from the
+ * trigger enters the panel, Tab from its last control continues after the trigger, and Shift+Tab
+ * walks the same way back. Tab from the last tab stop of the page skips the panel and leaves the
+ * document, as it would without teleport. Closing with focus inside puts focus back on the
+ * trigger.
+ */
+export const TeleportKeyboard: Story = {
+  render: () => ({
+    components: { FloatingPanel, NexxtButton },
+    template: `
+      <div style="display: flex; gap: 12px; align-items: center;">
+        <NexxtButton variant="secondary">Voor</NexxtButton>
+        <FloatingPanel teleport surface>
+          <template #trigger="{ toggle, isOpen }">
+            <NexxtButton variant="secondary" :aria-expanded="isOpen" @click="toggle">Trigger</NexxtButton>
+          </template>
+          <template #content>
+            <div style="display: flex; gap: 8px; padding: 12px;">
+              <NexxtButton variant="secondary">Knop 1</NexxtButton>
+              <NexxtButton variant="secondary">Knop 2</NexxtButton>
+            </div>
+          </template>
+        </FloatingPanel>
+        <NexxtButton variant="secondary">Na</NexxtButton>
+      </div>
+    `,
+  }),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+    const trigger = canvas.getByRole('button', { name: 'Trigger' })
+    await userEvent.click(trigger)
+    const first = await screen.findByRole('button', { name: 'Knop 1' })
+    const second = screen.getByRole('button', { name: 'Knop 2' })
+    const after = canvas.getByRole('button', { name: 'Na' })
+    await expect(canvasElement.contains(first)).toBe(false)
+    await expect(trigger).toHaveFocus()
+
+    for (const next of [first, second, after]) {
+      await userEvent.tab()
+      await expect(next).toHaveFocus()
+    }
+    for (const previous of [second, first, trigger]) {
+      await userEvent.tab({ shift: true })
+      await expect(previous).toHaveFocus()
+    }
+
+    // Escape from inside: focus goes back to the trigger instead of dropping to <body>
+    await userEvent.tab()
+    await expect(first).toHaveFocus()
+    await userEvent.keyboard('{Escape}')
+    await waitFor(() => expect(first).not.toBeInTheDocument())
+    await expect(trigger).toHaveFocus()
+  },
+}
+
+/**
+ * Inside a `role="dialog"` such as `NexxtModal`, `teleport` is ignored. Reka makes everything
+ * outside the dialog `pointer-events: none` and traps focus inside it, so a panel in `<body>`
+ * could not be clicked, a click on it would land on the overlay and close the modal, and focus
+ * would be pulled back into the dialog. The panel stays next to its trigger instead;
+ * `position: fixed` already escapes the dialog's overflow.
+ */
+export const TeleportInModal: Story = {
+  render: () => ({
+    components: { FloatingPanel, NexxtButton, NexxtModal },
+    setup() {
+      const open = ref(false)
+      const query = ref('')
+      return { open, query }
+    },
+    template: `
+      <NexxtButton @click="open = true">Open modal</NexxtButton>
+      <NexxtModal v-model="open" title="Modal with a floating panel">
+        <p style="margin: 0 0 12px; font-size: 13px; color: #4b5563;">
+          This panel sets <code>teleport</code>, but inside a dialog it is ignored: the panel stays
+          next to its trigger.
+        </p>
+        <FloatingPanel teleport surface>
+          <template #trigger="{ toggle, isOpen }">
+            <NexxtButton variant="secondary" :aria-expanded="isOpen" @click="toggle">Open panel</NexxtButton>
+          </template>
+          <template #content>
+            <div style="padding: 12px; width: 240px;">
+              <label style="display: flex; flex-direction: column; gap: 4px; font-size: 13px;">
+                Search
+                <input v-model="query" type="text" style="border: 1px solid #d1d5db; border-radius: 6px; padding: 6px 8px;" />
+              </label>
+            </div>
+          </template>
+        </FloatingPanel>
+      </NexxtModal>
+    `,
+  }),
+  play: async ({ canvasElement }) => {
+    // Closed on mount, so the Docs page is not covered by the scrim; the play opens it.
+    await userEvent.click(within(canvasElement).getByRole('button', { name: 'Open modal' }))
+    const dialog = await screen.findByRole('dialog')
+    const modal = within(dialog)
+    await userEvent.click(modal.getByRole('button', { name: 'Open panel' }))
+    const input = await modal.findByRole('textbox', { name: 'Search' })
+    await expect(dialog.contains(input)).toBe(true)
+
+    await userEvent.click(input)
+    await userEvent.type(input, 'abc')
+    await expect(input).toHaveFocus()
+    await expect(input).toHaveValue('abc')
+
+    await userEvent.click(input.closest('div')!)
+    await expect(screen.getByRole('dialog')).toBe(dialog)
+    await expect(input).toBeInTheDocument()
+  },
+}