feat(Tooltip): Portal tooltip to body by default to fix overflow clipping. Resolves #446 (#828)

* feat(Tooltip): Portal tooltip to body by default to fix overflow clipping.  Resolves #446

* feat(Tooltip): Add `fadeDuration` prop to control fade in/out transition

Author: techniq

.changeset/tooltip-fade-duration.md

@@ -0,0 +1,7 @@
+---
+'layerchart': minor
+---
+
+feat(Tooltip): Add `fadeDuration` prop to control fade in/out transition
+
+The fade transition on `Tooltip.Root` is now configurable via the `fadeDuration` prop (default: `100`ms). Set to `0` to disable the fade transition entirely.

.changeset/tooltip-portal.md

@@ -0,0 +1,7 @@
+---
+'layerchart': minor
+---
+
+feat(Tooltip): Portal tooltip to body by default to fix overflow clipping. Resolves #446
+
+Tooltip.Root now portals to `document.body` (or `.PortalTarget`) by default using the `portal` action from `@layerstack/svelte-actions`. This prevents tooltips from being clipped by ancestor elements with `overflow: hidden`. The tooltip uses `position: fixed` with viewport-relative coordinates when portaled. Set `portal={false}` to restore the previous inline behavior. Both `contained="container"` and `contained="window"` modes continue to work correctly with portaling.

docs/src/content/guides/tooltip.md

@@ -152,6 +152,33 @@ The `anchor` prop controls which corner of the tooltip aligns to the position po
 
 :example{ component="Tooltip" name="anchor-location" }
 
+### Portal
+
+By default, `Tooltip.Root` is portaled outside the chart DOM to `document.body` (or a `.PortalTarget` element if one exists). This prevents the tooltip from being clipped by ancestors with `overflow: hidden`.
+
+| Value                         | Behavior                                                    |
+| ----------------------------- | ----------------------------------------------------------- |
+| `true`                        | Portal to `.PortalTarget` or `document.body` (default)      |
+| `false`                       | Render inline within the chart (original behavior)          |
+| `{ target: '.my-container' }` | Portal to a specific CSS selector                           |
+| `{ target: element }`         | Portal to a specific DOM element                            |
+| `{ enabled: false }`          | Same as `false`                                             |
+
+```svelte
+<!-- Default: portaled to body -->
+<Tooltip.Root>
+
+<!-- Disable portal (inline positioning) -->
+<Tooltip.Root portal={false}>
+
+<!-- Portal to a custom target -->
+<Tooltip.Root portal={{ target: '.my-tooltip-container' }}>
+```
+
+Toggle `portal` off to see the tooltip clipped by the `overflow: hidden` container:
+
+:example{ component="Tooltip" name="portal-overflow" }
+
 ### Containment
 
 Tooltips are contained within their chart container by default, flipping sides when they would overflow. The `contained` prop controls this:

docs/src/examples/components/Tooltip/anchor-location.svelte

@@ -17,11 +17,12 @@
 	let anchor: ComponentProps<typeof Tooltip.Root>['anchor'] = $state('top-left');
 	let snap: 'pointer' | 'data' = $state('pointer');
 	let contained: ComponentProps<typeof Tooltip.Root>['contained'] = $state('container');
+	let portal: boolean = $state(true);
 
 	export { data };
 </script>
 
-<TooltipContextControls2 bind:anchor bind:snap bind:contained />
+<TooltipContextControls2 bind:anchor bind:snap bind:contained bind:portal />
 
 <Chart
 	{data}
@@ -46,6 +47,7 @@
 		y={snap}
 		yOffset={['left', 'center', 'right'].includes(anchor ?? '') ? 0 : 10}
 		{contained}
+		{portal}
 	>
 		{#snippet children({ data })}
 			<Tooltip.Header value={data.date} format="day" />

docs/src/examples/components/Tooltip/portal-overflow.svelte

@@ -0,0 +1,50 @@
+<script lang="ts">
+	import { Field, Switch } from 'svelte-ux';
+	import { Area, Axis, Chart, Layer, Highlight, Tooltip, defaultChartPadding } from 'layerchart';
+	import { createDateSeries } from '$lib/utils/data.js';
+
+	const data = createDateSeries({
+		count: 30,
+		min: 20,
+		max: 100,
+		value: 'integer',
+		keys: ['value']
+	});
+
+	let portal: boolean = $state(true);
+
+	export { data };
+</script>
+
+<div class="flex gap-2 mb-4 screenshot-hidden">
+	<Field label="Portal">
+		<Switch bind:checked={portal} />
+	</Field>
+</div>
+
+<div class="overflow-hidden rounded border p-2" style:height="200px">
+	<Chart
+		{data}
+		x="date"
+		y="value"
+		yDomain={[0, null]}
+		yNice
+		padding={defaultChartPadding({ top: 5, left: 28, bottom: 24, right: 15 })}
+		tooltipContext={{ mode: 'quadtree-x' }}
+	>
+		<Layer>
+			<Axis placement="left" grid rule />
+			<Axis placement="bottom" rule />
+			<Area class="fill-primary/30" line={{ class: 'stroke-primary stroke-2' }} />
+			<Highlight points lines />
+		</Layer>
+		<Tooltip.Root {portal} contained={false}>
+			{#snippet children({ data })}
+				<Tooltip.Header value={data.date} format="day" />
+				<Tooltip.List>
+					<Tooltip.Item label="value" value={data.value} />
+				</Tooltip.List>
+			{/snippet}
+		</Tooltip.Root>
+	</Chart>
+</div>

docs/src/lib/components/controls/TooltipContextControls2.svelte

@@ -1,12 +1,13 @@
 <script lang="ts">
 	import type { ComponentProps } from 'svelte';
-	import { Button, Field, Menu, MenuField, Toggle } from 'svelte-ux';
+	import { Button, Field, Menu, MenuField, Switch, Toggle } from 'svelte-ux';
 	import { Tooltip } from 'layerchart';
 
 	interface Props {
 		anchor?: ComponentProps<typeof Tooltip.Root>['anchor'];
 		snap?: 'pointer' | 'data';
 		contained?: ComponentProps<typeof Tooltip.Root>['contained'];
+		portal?: boolean;
 	}
 
 	const anchorOptions = [
@@ -24,7 +25,8 @@
 	let {
 		anchor = $bindable('top-left' as ComponentProps<typeof Tooltip.Root>['anchor']),
 		snap = $bindable('pointer' as 'pointer' | 'data'),
-		contained = $bindable(false as ComponentProps<typeof Tooltip.Root>['contained'])
+		contained = $bindable(false as ComponentProps<typeof Tooltip.Root>['contained']),
+		portal = $bindable(true)
 	}: Props = $props();
 </script>
 
@@ -59,13 +61,19 @@
 		]}
 	/>
 
-	<MenuField
-		label="Contained"
-		bind:value={contained}
-		options={[
-			{ label: 'none', value: false },
-			{ label: 'container', value: 'container' },
-			{ label: 'window', value: 'window' }
-		]}
-	/>
+	<div class="flex gap-2">
+		<MenuField
+			label="Contained"
+			bind:value={contained}
+			options={[
+				{ label: 'none', value: false },
+				{ label: 'container', value: 'container' },
+				{ label: 'window', value: 'window' }
+			]}
+			class="flex-1"
+		/>
+		<Field label="Portal">
+			<Switch bind:checked={portal} />
+		</Field>
+	</div>
 </div>

packages/layerchart/src/lib/components/charts/BarChart.svelte.test.ts

@@ -294,7 +294,7 @@ describe('BarChart', () => {
       tooltipRect!.dispatchEvent(new PointerEvent('pointermove', eventInit));
 
       await vi.waitFor(() => {
-        const colorDots = container.querySelectorAll('.lc-tooltip-item-color');
+        const colorDots = document.querySelectorAll('.lc-tooltip-item-color');
         expect(colorDots.length).toBe(4);
 
         const colors = Array.from(colorDots).map((dot) =>

packages/layerchart/src/lib/components/charts/DefaultTooltip.svelte.test.ts

@@ -59,16 +59,16 @@ describe('DefaultTooltip', () => {
       triggerTooltip(tooltipCtx);
 
       await vi.waitFor(() => {
-        // Should have a header
-        const header = container.querySelector('.lc-tooltip-header');
+        // Should have a header (portaled to body)
+        const header = document.querySelector('.lc-tooltip-header');
         expect(header).not.toBeNull();
 
         // Should have 4 tooltip items (3 series + 1 total)
-        const items = container.querySelectorAll('.lc-tooltip-item-root');
+        const items = document.querySelectorAll('.lc-tooltip-item-root');
         expect(items.length).toBe(4);
 
         // Labels should match series keys + total
-        const labels = container.querySelectorAll('.lc-tooltip-item-label');
+        const labels = document.querySelectorAll('.lc-tooltip-item-label');
         expect(labels.length).toBe(4);
         const labelTexts = Array.from(labels).map((l) => l.textContent?.trim());
         expect(labelTexts).toEqual(['apples', 'bananas', 'oranges', 'total']);
@@ -89,7 +89,7 @@ describe('DefaultTooltip', () => {
       triggerTooltip(tooltipCtx);
 
       await vi.waitFor(() => {
-        const colorDots = container.querySelectorAll('.lc-tooltip-item-color');
+        const colorDots = document.querySelectorAll('.lc-tooltip-item-color');
         expect(colorDots.length).toBe(3);
         const colors = Array.from(colorDots).map((dot) =>
           (dot as HTMLElement).style.getPropertyValue('--color')
@@ -112,15 +112,15 @@ describe('DefaultTooltip', () => {
       triggerTooltip(tooltipCtx);
 
       await vi.waitFor(() => {
-        const items = container.querySelectorAll('.lc-tooltip-item-root');
+        const items = document.querySelectorAll('.lc-tooltip-item-root');
         expect(items.length).toBe(4);
       });
 
       const items = Array.from(
-        container.querySelectorAll('.lc-tooltip-item-root')
+        document.querySelectorAll('.lc-tooltip-item-root')
       ) as HTMLElement[];
       const labels = Array.from(
-        container.querySelectorAll('.lc-tooltip-item-label')
+        document.querySelectorAll('.lc-tooltip-item-label')
       ) as HTMLElement[];
 
       triggerPointerEvent(items[0], 'pointerenter');
@@ -164,7 +164,7 @@ describe('DefaultTooltip', () => {
       triggerTooltip(tooltipCtx);
 
       await vi.waitFor(() => {
-        const items = container.querySelectorAll('.lc-tooltip-item-root');
+        const items = document.querySelectorAll('.lc-tooltip-item-root');
         // 1 series item, no total
         expect(items.length).toBe(1);
       });
@@ -186,14 +186,14 @@ describe('DefaultTooltip', () => {
       triggerTooltip(tooltipCtx);
 
       await vi.waitFor(() => {
-        const header = container.querySelector('.lc-tooltip-header');
+        const header = document.querySelector('.lc-tooltip-header');
         expect(header).not.toBeNull();
 
         // 3 series + 1 total = 4 items
-        const items = container.querySelectorAll('.lc-tooltip-item-root');
+        const items = document.querySelectorAll('.lc-tooltip-item-root');
         expect(items.length).toBe(4);
 
-        const labels = container.querySelectorAll('.lc-tooltip-item-label');
+        const labels = document.querySelectorAll('.lc-tooltip-item-label');
         const labelTexts = Array.from(labels).map((l) => l.textContent?.trim());
         expect(labelTexts).toEqual(['apples', 'bananas', 'oranges', 'total']);
       });
@@ -215,11 +215,11 @@ describe('DefaultTooltip', () => {
       triggerTooltip(tooltipCtx);
 
       await vi.waitFor(() => {
-        const items = container.querySelectorAll('.lc-tooltip-item-root');
+        const items = document.querySelectorAll('.lc-tooltip-item-root');
         // Should show x and y items
         expect(items.length).toBe(2);
 
-        const labels = Array.from(container.querySelectorAll('.lc-tooltip-item-label')).map((l) =>
+        const labels = Array.from(document.querySelectorAll('.lc-tooltip-item-label')).map((l) =>
           l.textContent?.trim()
         );
         expect(labels).toEqual(['x', 'y']);
@@ -241,11 +241,11 @@ describe('DefaultTooltip', () => {
       triggerTooltip(tooltipCtx);
 
       await vi.waitFor(() => {
-        const items = container.querySelectorAll('.lc-tooltip-item-root');
+        const items = document.querySelectorAll('.lc-tooltip-item-root');
         // Should show x, y, and r items
         expect(items.length).toBe(3);
 
-        const labels = Array.from(container.querySelectorAll('.lc-tooltip-item-label')).map((l) =>
+        const labels = Array.from(document.querySelectorAll('.lc-tooltip-item-label')).map((l) =>
           l.textContent?.trim()
         );
         expect(labels).toEqual(['x', 'y', 'size']);
@@ -270,12 +270,12 @@ describe('DefaultTooltip', () => {
 
       await vi.waitFor(() => {
         // Should show a header with the series name
-        const header = container.querySelector('.lc-tooltip-header');
+        const header = document.querySelector('.lc-tooltip-header');
         expect(header).not.toBeNull();
         expect(header!.textContent).not.toBe('');
 
         // Should show x and y items
-        const items = container.querySelectorAll('.lc-tooltip-item-root');
+        const items = document.querySelectorAll('.lc-tooltip-item-root');
         expect(items.length).toBe(2);
       });
     });

packages/layerchart/src/lib/components/charts/LineChart.svelte.test.ts

@@ -40,7 +40,7 @@ describe('LineChart', () => {
     tooltipRect!.dispatchEvent(new PointerEvent('pointermove', eventInit));
 
     await vi.waitFor(() => {
-      const colorDot = container.querySelector('.lc-tooltip-item-color') as HTMLElement | null;
+      const colorDot = document.querySelector('.lc-tooltip-item-color') as HTMLElement | null;
       expect(colorDot).not.toBeNull();
 
       const color = colorDot!.style.getPropertyValue('--color');

packages/layerchart/src/lib/components/charts/PieChart.svelte.test.ts

@@ -34,8 +34,8 @@ describe('PieChart', () => {
     arc!.dispatchEvent(new PointerEvent('pointermove', eventInit));
 
     await vi.waitFor(() => {
-      const tooltipLabel = container.querySelector('.lc-tooltip-item-label');
-      const tooltipValue = container.querySelector('.lc-tooltip-item-value');
+      const tooltipLabel = document.querySelector('.lc-tooltip-item-label');
+      const tooltipValue = document.querySelector('.lc-tooltip-item-value');
 
       expect(tooltipLabel?.textContent).toContain('chrome');
       expect(tooltipValue?.textContent).toContain('275');