entasis 0.11.0 → 0.12.0

package/dist/components/ScrollArea/ScrollArea.svelte

@@ -5,28 +5,56 @@
 	import { useScrollAreaTheme } from './scrollArea.theme.js';
 	import { caretUpIcon } from '../Icons/caretUp.js';
 	import { caretDownIcon } from '../Icons/caretDown.js';
-	import { useI18n } from '../../i18n/context.svelte.js';
+	import { getI18nDirection, useI18n } from '../../i18n/context.svelte.js';
+	import { presence } from '../../utils/stateAttributes.js';
+	import { useDirection } from '../../utils/useDirection.svelte.js';
+	import { untrack } from 'svelte';
 
 	let {
 		ref = $bindable(null),
 		viewportRef = $bindable(null),
 		label,
-		viewportRole = 'group',
+		viewportRole,
+		viewportAttrs,
 		class: className = '',
 		children,
 		delay = 0,
 		type = 'hover',
 		scrollOnEdges = false,
 		scrollFade = false,
+		overflowEdgeThreshold = 1,
 		onscroll,
 		theme,
 		...attachments
 	}: ScrollAreaProps = $props();
 	const t = $derived(useI18n());
 
+	const MERGED_VIEWPORT_ATTRS = [
+		'role',
+		'aria-label',
+		'tabindex',
+		'class',
+		'onscroll',
+		'onfocus',
+		'onblur'
+	];
+
 	const componentId = $props.id();
 	const viewportId = `${componentId}-viewport`;
 
+	// The horizontal offset of an RTL viewport is negative. The element's own computed direction
+	// wins (a `dir="ltr"` code block inside an RTL page), the i18n direction covers what a
+	// computed style cannot say.
+	const i18nDirection = getI18nDirection();
+	const resolveDirection = useDirection(
+		() => viewportRef,
+		() => {
+			if (!viewportRef || typeof getComputedStyle !== 'function') return undefined;
+			const computed = getComputedStyle(viewportRef).direction;
+			return computed === 'rtl' || computed === 'ltr' ? computed : undefined;
+		}
+	);
+
 	const scrollArea = new ScrollArea({
 		get type() {
 			return type;
@@ -36,7 +64,19 @@
 		},
 		get scrollOnEdges() {
 			return scrollOnEdges;
-		}
+		},
+		get overflowEdgeThreshold() {
+			return overflowEdgeThreshold;
+		},
+		direction: () => resolveDirection()
+	});
+
+	// A direction change (a locale switch, a `dir` flip) moves no box the observers watch.
+	$effect(() => {
+		// The computed direction answers first, so the i18n context is read here to subscribe.
+		void i18nDirection?.();
+		void resolveDirection();
+		untrack(() => scrollArea.measure());
 	});
 
 	const scrollFadeAxis = $derived.by(() => {
@@ -47,33 +87,126 @@
 	});
 
 	const classes = $derived(useScrollAreaTheme(theme));
+
+	// Accessibility of the viewport. An idle viewport is a plain div: it adds no role, no name and
+	// no tab stop, so a scroll area that fits its content (a short Select list, a card) is invisible
+	// to assistive tech. It becomes a named, focusable `group` only while it overflows (WCAG SCR34),
+	// or keeps the role and name the caller passed. A presentational viewport (`presentation` /
+	// `none`) stays transparent even while it overflows: the surrounding widget (a listbox with
+	// active-descendant navigation, say) owns keyboard scrolling, and a focusable or named node
+	// would cancel the presentational role.
+	//
+	// A caller that makes the viewport its own widget passes `viewportAttrs` with a `role`: the
+	// caller then owns the name and the tab stop as well, and the viewport adds neither.
+	//
+	// A viewport that holds focus keeps its role, name and a programmatic tab stop (-1) after its
+	// content stops overflowing (a resize, a zoom-out, filtered content): removing the tabindex of
+	// the focused element would make the browser drop focus to <body>. They go once it blurs.
+	let viewportFocused = $state(false);
+	const exposed = $derived(scrollArea.overflowing || viewportFocused);
+	const ownedRole = $derived(viewportAttrs?.role);
+	const effectiveRole = $derived(ownedRole ?? viewportRole);
+	const presentational = $derived(effectiveRole === 'presentation' || effectiveRole === 'none');
+	const resolvedViewportRole = $derived(
+		ownedRole ?? viewportRole ?? (label !== undefined || exposed ? 'group' : undefined)
+	);
+	const resolvedViewportLabel = $derived(
+		viewportAttrs?.['aria-label'] ??
+			(presentational
+				? undefined
+				: (label ??
+					(exposed && ownedRole === undefined && !viewportAttrs?.['aria-labelledby']
+						? t.scrollableContent
+						: undefined)))
+	);
+	const resolvedViewportTabindex = $derived(
+		viewportAttrs?.tabindex ??
+			(presentational || ownedRole !== undefined
+				? undefined
+				: scrollArea.overflowing
+					? 0
+					: viewportFocused
+						? -1
+						: undefined)
+	);
+	// Everything else the caller passes goes straight onto the viewport. The properties above, the
+	// class and the handlers are merged instead, so they are left out here.
+	const viewportExtra = $derived.by(() => {
+		const extra: Record<PropertyKey, unknown> = { ...viewportAttrs };
+		for (const key of MERGED_VIEWPORT_ATTRS) delete extra[key];
+		return extra;
+	});
+
+	// Bars show while the area is hovered or scrolling in `hover` mode: touch scrolling, which
+	// never hovers, still reveals them.
+	const showScrollbarY = $derived(
+		scrollArea.isDraggingY ||
+			(scrollArea.visible &&
+				(type === 'always' ||
+					type === 'auto' ||
+					(type === 'hover' && (scrollArea.hoover.isHovered || scrollArea.isScrolling)) ||
+					(type === 'scroll' && scrollArea.isScrolling)))
+	);
+	const showScrollbarX = $derived(
+		scrollArea.isDraggingX ||
+			(scrollArea.visibleX &&
+				(type === 'always' ||
+					type === 'auto' ||
+					(type === 'hover' && (scrollArea.hoover.isHovered || scrollArea.isScrolling)) ||
+					(type === 'scroll' && scrollArea.isScrolling)))
+	);
+	const scrolling = $derived(presence(scrollArea.isScrolling));
 </script>
 
 <div
 	data-scroll-area
 	data-slot="scroll-area"
+	data-scrolling={scrolling}
+	data-has-overflow-x={presence(scrollArea.visibleX)}
+	data-has-overflow-y={presence(scrollArea.visible)}
+	data-overflow-x-start={presence(scrollArea.hasOverflowXStart)}
+	data-overflow-x-end={presence(scrollArea.hasOverflowXEnd)}
+	data-overflow-y-start={presence(scrollArea.hasOverflowYStart)}
+	data-overflow-y-end={presence(scrollArea.hasOverflowYEnd)}
 	bind:this={ref}
 	class={classes.root({ className })}
 	style:position="relative"
+	style:--scroll-area-overflow-x-start="{scrollArea.overflowXStart}px"
+	style:--scroll-area-overflow-x-end="{scrollArea.overflowXEnd}px"
+	style:--scroll-area-overflow-y-start="{scrollArea.overflowYStart}px"
+	style:--scroll-area-overflow-y-end="{scrollArea.overflowYEnd}px"
 	{@attach scrollArea.hoover.reference}
 	{@attach scrollArea.scrollOnEdgesAttachment}
 	{...attachments}
 >
 	<!-- The viewport is the native scroll container and the keyboard scroll region: focusable
 	     only when it overflows (WCAG SCR34 scrollable-region pattern), so it never becomes a
-	     dead tab stop. -->
+	     dead tab stop. Role, name and tab stop resolve in the script above. -->
 	<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
 	<div
 		id={viewportId}
+		{...viewportExtra}
 		data-scroll-area-viewport
 		data-slot="scroll-area-viewport"
+		data-scrolling={scrolling}
 		data-scroll-fade-axis={scrollFadeAxis === 'none' ? undefined : scrollFadeAxis}
 		bind:this={viewportRef}
-		class={classes.viewport({ scrollFade: scrollFadeAxis })}
-		tabindex={scrollArea.viewportTabindex}
-		role={viewportRole}
-		aria-label={label ?? t.scrollableContent}
-		{onscroll}
+		class={classes.viewport({ scrollFade: scrollFadeAxis, className: viewportAttrs?.class })}
+		tabindex={resolvedViewportTabindex}
+		role={resolvedViewportRole}
+		aria-label={resolvedViewportLabel}
+		onscroll={(event) => {
+			viewportAttrs?.onscroll?.(event);
+			onscroll?.(event);
+		}}
+		onfocus={(event) => {
+			viewportAttrs?.onfocus?.(event);
+			viewportFocused = true;
+		}}
+		onblur={(event) => {
+			viewportAttrs?.onblur?.(event);
+			viewportFocused = false;
+		}}
 		{@attach scrollArea.viewportAttachment}
 		style:position="relative"
 		style:overflow="scroll"
@@ -97,71 +230,76 @@
 		</div>
 	</div>
 
-	{#if (type === 'hover' && scrollArea.visible && scrollArea.hoover.isHovered) || scrollArea.isDraggingY || (type === 'always' && scrollArea.visible) || (type === 'auto' && scrollArea.visible) || (type === 'scroll' && scrollArea.isScrolling)}
+	<!-- The scrollbars are pointer-only affordances: the viewport is the keyboard scroll region, so
+	     the tracks stay out of the accessibility tree instead of exposing an unreachable
+	     role="scrollbar" (inside a listbox they would also be invalid children). Where both bars
+	     show, each stops short of the other at the corner. -->
+	{#if showScrollbarY}
 		<div
 			data-slot="scroll-area-scrollbar"
+			data-orientation="vertical"
+			data-scrolling={scrolling}
 			transition:fade={{ duration: 200 }}
 			bind:this={scrollArea.scrollbarYElement}
 			class={classes.scrollbar()}
-			style="bottom: 0px"
+			style:bottom="{scrollArea.trackXThickness}px"
 			style:display="flex"
 			style:user-select="none"
 			style:opacity={scrollArea.visible ? 1 : 0}
 			style:transition="opacity 0.2s ease"
-			role="scrollbar"
-			aria-controls={viewportId}
-			aria-valuenow={scrollArea.scrollY}
-			aria-valuemin="0"
-			aria-valuemax={scrollArea.maxScrollY}
+			aria-hidden="true"
 			{@attach scrollArea.trackAttachment}
 			{@attach scrollArea.trackRect.reference}
 		>
 			<div
 				data-thumb
 				data-slot="scroll-area-thumb"
+				data-orientation="vertical"
+				data-scrolling={scrolling}
 				class={classes.scrollbarThumb()}
 				style:height={scrollArea.thumbYSize + 'px'}
 				style:width="100%"
 				style:transform={`translateY(${scrollArea.thumbYPosition}px)`}
-				{@attach scrollArea.dragY.reference}
+				{@attach scrollArea.dragY}
 				{@attach scrollArea.thumbRect.reference}
 			></div>
 		</div>
 	{/if}
 
-	{#if (type === 'hover' && scrollArea.visibleX && scrollArea.hoover.isHovered) || scrollArea.isDraggingX || (type === 'always' && scrollArea.visibleX) || (type === 'auto' && scrollArea.visibleX) || (type === 'scroll' && scrollArea.isScrolling)}
+	{#if showScrollbarX}
 		<div
 			data-slot="scroll-area-scrollbar"
+			data-orientation="horizontal"
+			data-scrolling={scrolling}
 			transition:fade={{ duration: 200 }}
 			bind:this={scrollArea.scrollbarXElement}
 			class={classes.scrollbarX()}
-			style="right: 0px"
+			style:inset-inline-end="{scrollArea.trackYThickness}px"
 			style:display="flex"
 			style:user-select="none"
 			style:opacity={scrollArea.visibleX ? 1 : 0}
 			style:transition="opacity 0.2s ease"
-			role="scrollbar"
-			aria-orientation="horizontal"
-			aria-controls={viewportId}
-			aria-valuenow={scrollArea.scrollX}
-			aria-valuemin="0"
-			aria-valuemax={scrollArea.maxScrollX}
+			aria-hidden="true"
 			{@attach scrollArea.trackAttachmentX}
+			{@attach scrollArea.trackRectX.reference}
 		>
 			<div
 				data-thumb
 				data-slot="scroll-area-thumb"
+				data-orientation="horizontal"
+				data-scrolling={scrolling}
 				class={classes.scrollbarThumb()}
 				style:width={scrollArea.thumbXSize + 'px'}
 				style:height="100%"
-				style:transform={`translateX(${scrollArea.thumbXPosition}px)`}
-				{@attach scrollArea.dragX.reference}
+				style:transform={`translateX(${scrollArea.thumbXTranslate}px)`}
+				{@attach scrollArea.dragX}
 			></div>
 		</div>
 	{/if}
 	{#if scrollArea.scrollOnEdgesAttachment}
 		{#if scrollArea.canScrollUp}
 			<div
+				aria-hidden="true"
 				class="absolute top-0 left-0 flex w-full items-center justify-center"
 				style:pointer-events="none"
 			>
@@ -171,6 +309,7 @@
 
 		{#if scrollArea.canScrollDown}
 			<div
+				aria-hidden="true"
 				class="absolute bottom-0 left-0 flex w-full items-center justify-center"
 				style:pointer-events="none"
 			>

package/dist/components/ScrollArea/index.d.ts

@@ -1,3 +1,4 @@
 export { default as ScrollArea } from './ScrollArea.svelte';
-export type { ScrollAreaProps } from './scrollArea.props.js';
+export type { ScrollAreaProps, ScrollAreaViewportAttributes } from './scrollArea.props.js';
 export { scrollAreaTheme, setScrollAreaTheme, useScrollAreaTheme, type ScrollAreaTheme, type ScrollAreaThemeProps } from './scrollArea.theme.js';
+export { scrollAreaDataAttributes, scrollAreaCssVariables, type ScrollAreaDataAttribute, type ScrollAreaCssVariable } from './scrollArea.attributes.js';

package/dist/components/ScrollArea/index.js

@@ -1,2 +1,3 @@
 export { default as ScrollArea } from './ScrollArea.svelte';
 export { scrollAreaTheme, setScrollAreaTheme, useScrollAreaTheme } from './scrollArea.theme.js';
+export { scrollAreaDataAttributes, scrollAreaCssVariables } from './scrollArea.attributes.js';

package/dist/components/ScrollArea/scrollArea.attributes.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The styling hooks a ScrollArea exposes. Attributes are presence attributes (`''` while the
+ * state holds, omitted otherwise) unless the description says they carry a value; the variables
+ * are set on the root element in px.
+ */
+export declare const scrollAreaDataAttributes: {
+    readonly 'data-scrolling': "On the root, the viewport, the scrollbars and the thumbs: present from the first scroll event until the viewport has been idle for 400 ms.";
+    readonly 'data-has-overflow-x': "On the root: present while the content overflows horizontally.";
+    readonly 'data-has-overflow-y': "On the root: present while the content overflows vertically.";
+    readonly 'data-overflow-x-start': "On the root: present while content is hidden past the inline start edge (to the left in LTR, to the right in RTL).";
+    readonly 'data-overflow-x-end': "On the root: present while content is hidden past the inline end edge (to the right in LTR, to the left in RTL).";
+    readonly 'data-overflow-y-start': "On the root: present while content is hidden above the viewport.";
+    readonly 'data-overflow-y-end': "On the root: present while content is hidden below the viewport.";
+    readonly 'data-orientation': "On the scrollbars and thumbs: `vertical` or `horizontal`, the axis they scroll.";
+};
+/** The name of a ScrollArea data attribute. */
+export type ScrollAreaDataAttribute = keyof typeof scrollAreaDataAttributes;
+export declare const scrollAreaCssVariables: {
+    readonly '--scroll-area-overflow-x-start': "Px of content hidden past the inline start edge (0 while the axis does not overflow).";
+    readonly '--scroll-area-overflow-x-end': "Px of content hidden past the inline end edge (0 while the axis does not overflow).";
+    readonly '--scroll-area-overflow-y-start': "Px of content hidden above the viewport.";
+    readonly '--scroll-area-overflow-y-end': "Px of content hidden below the viewport.";
+};
+/** The name of a ScrollArea CSS variable. */
+export type ScrollAreaCssVariable = keyof typeof scrollAreaCssVariables;

package/dist/components/ScrollArea/scrollArea.attributes.js

@@ -0,0 +1,21 @@
+/**
+ * The styling hooks a ScrollArea exposes. Attributes are presence attributes (`''` while the
+ * state holds, omitted otherwise) unless the description says they carry a value; the variables
+ * are set on the root element in px.
+ */
+export const scrollAreaDataAttributes = {
+    'data-scrolling': 'On the root, the viewport, the scrollbars and the thumbs: present from the first scroll event until the viewport has been idle for 400 ms.',
+    'data-has-overflow-x': 'On the root: present while the content overflows horizontally.',
+    'data-has-overflow-y': 'On the root: present while the content overflows vertically.',
+    'data-overflow-x-start': 'On the root: present while content is hidden past the inline start edge (to the left in LTR, to the right in RTL).',
+    'data-overflow-x-end': 'On the root: present while content is hidden past the inline end edge (to the right in LTR, to the left in RTL).',
+    'data-overflow-y-start': 'On the root: present while content is hidden above the viewport.',
+    'data-overflow-y-end': 'On the root: present while content is hidden below the viewport.',
+    'data-orientation': 'On the scrollbars and thumbs: `vertical` or `horizontal`, the axis they scroll.'
+};
+export const scrollAreaCssVariables = {
+    '--scroll-area-overflow-x-start': 'Px of content hidden past the inline start edge (0 while the axis does not overflow).',
+    '--scroll-area-overflow-x-end': 'Px of content hidden past the inline end edge (0 while the axis does not overflow).',
+    '--scroll-area-overflow-y-start': 'Px of content hidden above the viewport.',
+    '--scroll-area-overflow-y-end': 'Px of content hidden below the viewport.'
+};

package/dist/components/ScrollArea/scrollArea.mcp.d.ts

@@ -1 +1 @@
-export declare const scrollAreaDescription = "\n# ScrollArea Component\n\nThe ScrollArea component provides a native scroll viewport with custom overlay scrollbars.\n\n## Basic Usage\n\n```svelte\n<ScrollArea class=\"h-64\">\n\t{#each items as item}\n\t\t<div>{item}</div>\n\t{/each}\n</ScrollArea>\n```\n\n## Props\n\n### Core Props\n- **children**: Snippet - Content rendered inside the scrollable viewport\n- **ref**: HTMLElement | null (bindable) - Reference to the root scroll-area element\n- **viewportRef**: HTMLElement | null (bindable) - Reference to the native scrolling viewport, suitable for virtualizers and imperative scrolling\n- Native div attributes and attachments are forwarded to the root element\n- **label**: string (default: 'Scrollable content') - Accessible name for the native scrolling viewport\n- **viewportRole**: string (default: 'group') - Role of the scrolling viewport; set it to the role the surrounding structure expects (`rowgroup` inside a grid or treegrid, for instance)\n- **type**: 'hover' | 'always' | 'scroll' | 'auto' (default: 'hover') - Controls scrollbar visibility behavior\n- **delay**: number (default: 0) - Milliseconds before hover mode treats the area as hovered\n- **onscroll**: (event: Event) => void - Native scroll handler attached to the viewport\n\n### Behavior Props\n- **scrollOnEdges**: boolean (default: false) - Enables auto-scroll and up/down indicators when the pointer rests near the viewport edges\n- **scrollFade**: boolean (default: false) - Applies the shared `scroll-fade` utility to the scrollable viewport\n\n### Styling Props\n- **class**: string - Additional CSS classes for the root scroll area\n- **theme**: ScrollAreaThemeProps - Custom theme overrides\n\n## Examples\n\n### With Scroll Fade\n```svelte\n<ScrollArea class=\"h-64\" scrollFade>\n\t{#each items as item}\n\t\t<div>{item}</div>\n\t{/each}\n</ScrollArea>\n```\n\n### Always Visible Scrollbar\n```svelte\n<ScrollArea class=\"h-64\" type=\"always\">\n\tContent\n</ScrollArea>\n```\n\n### Edge Auto Scroll\n```svelte\n<ScrollArea class=\"h-64\" scrollOnEdges>\n\tContent\n</ScrollArea>\n```\n\n## Notes\n\n- The viewport is the native scroll container.\n- The `scrollFade` prop applies the utility to the viewport, not the outer wrapper.\n- Native browser scrollbars are hidden while custom scrollbar thumbs are rendered over the viewport.\n- Keyboard focus is applied only when the viewport overflows.\n\n## Theme Structure\n\nThe theme object contains:\n- **root**: Main scroll area container styles\n- **viewport**: Scrollable viewport container styles\n- **content**: Scrollable content wrapper styles\n- **scrollbar**: Vertical scrollbar track styles\n- **scrollbarX**: Horizontal scrollbar track styles\n- **scrollbarThumb**: Scrollbar thumb styles\n\n## Available Variants\n\n**viewport**:\n- scrollFade: 'none' | 'y' | 'x' - Adds the shared vertical or horizontal scroll-fade utility\n";
+export declare const scrollAreaDescription = "\n# ScrollArea Component\n\nThe ScrollArea component provides a native scroll viewport with custom overlay scrollbars.\n\n## Basic Usage\n\n```svelte\n<ScrollArea class=\"h-64\">\n\t{#each items as item}\n\t\t<div>{item}</div>\n\t{/each}\n</ScrollArea>\n```\n\n## Props\n\n### Core Props\n- **children**: Snippet - Content rendered inside the scrollable viewport\n- **ref**: HTMLElement | null (bindable) - Reference to the root scroll-area element\n- **viewportRef**: HTMLElement | null (bindable) - Reference to the native scrolling viewport, suitable for virtualizers and imperative scrolling\n- Native div attributes and attachments are forwarded to the root element\n- **label**: string - Accessible name for the native scrolling viewport; passing it makes the viewport a named `group` even when its content fits. Without it the viewport is named 'Scrollable content' (i18n `scrollableContent`) only while it overflows\n- **viewportAttrs**: attributes, handlers and attachments spread onto the scrolling viewport, for a widget that makes the viewport its own element (a listbox: `role`, `aria-activedescendant`, `id`). They win over the viewport's own: `class` is added to its classes, and `onscroll`, `onfocus` and `onblur` run before the built-in handling. A `role` here hands the viewport's semantics to the caller: the viewport then adds neither the automatic 'Scrollable content' name nor the automatic tab stop, so pass `tabindex` and a name when the role needs them\n- **viewportRole**: string - Role of the scrolling viewport. Without it the viewport is a plain element while its content fits and a `group` while it overflows (or when `label` is passed). Set it to the role the surrounding structure expects (`rowgroup` inside a grid or treegrid, for instance); inside a listbox pass `presentation`, which keeps the viewport unnamed and out of the tab order even while it overflows\n- **type**: 'hover' | 'always' | 'scroll' | 'auto' (default: 'hover') - Controls scrollbar visibility. `hover` shows the bars while the pointer is over the area or the area is scrolling, so touch scrolling (which never hovers) reveals them too; `always` and `auto` show them whenever the content overflows; `scroll` shows them only while scrolling\n- **overflowEdgeThreshold**: number (default: 1) - Px of content that may stay hidden past an edge before `data-overflow-*-start` / `data-overflow-*-end` (and the `scrollOnEdges` arrows) count it\n- **delay**: number (default: 0) - Milliseconds before hover mode treats the area as hovered\n- **onscroll**: (event: Event) => void - Native scroll handler attached to the viewport\n\n### Behavior Props\n- **scrollOnEdges**: boolean (default: false) - Enables auto-scroll and up/down indicators when the pointer rests near the viewport edges\n- **scrollFade**: boolean (default: false) - Applies the shared `scroll-fade` utility to the scrollable viewport\n\n### Styling Props\n- **class**: string - Additional CSS classes for the root scroll area\n- **theme**: ScrollAreaThemeProps - Custom theme overrides\n\n## Examples\n\n### With Scroll Fade\n```svelte\n<ScrollArea class=\"h-64\" scrollFade>\n\t{#each items as item}\n\t\t<div>{item}</div>\n\t{/each}\n</ScrollArea>\n```\n\n### Always Visible Scrollbar\n```svelte\n<ScrollArea class=\"h-64\" type=\"always\">\n\tContent\n</ScrollArea>\n```\n\n### Edge Auto Scroll\n```svelte\n<ScrollArea class=\"h-64\" scrollOnEdges>\n\tContent\n</ScrollArea>\n```\n\n## Notes\n\n- The viewport is the native scroll container.\n- The `scrollFade` prop applies the utility to the viewport, not the outer wrapper.\n- Native browser scrollbars are hidden while custom scrollbar thumbs are rendered over the viewport.\n- Keyboard focus is applied only when the viewport overflows.\n\n## Accessibility\n\n- A viewport whose content fits is a plain element: no role, no name, no tab stop.\n- While it overflows, the viewport is a `group` named by `label` (default 'Scrollable content') with `tabindex=\"0\"`, so keyboard users can scroll it (WCAG SCR34).\n- A focused viewport whose content stops overflowing keeps its role, name and `tabindex=\"-1\"` until it blurs, so focus never drops to the page.\n- `viewportRole=\"presentation\"` (or `none`) keeps the viewport transparent even while it overflows; use it when a surrounding listbox or grid owns keyboard scrolling.\n- The custom scrollbars and the edge-scroll arrows are pointer-only and carry `aria-hidden=\"true\"`.\n\n## Styling hooks\n\nData attributes (presence attributes, set to `\"\"` while the state holds):\n\n- `data-scrolling` on the root, viewport, scrollbars and thumbs: from the first scroll event until the viewport has been idle for 400 ms\n- `data-has-overflow-x` / `data-has-overflow-y` on the root: the content overflows on that axis\n- `data-overflow-x-start`, `data-overflow-x-end`, `data-overflow-y-start`, `data-overflow-y-end` on the root: content is hidden past that edge by more than `overflowEdgeThreshold`. The x edges are logical (inline start / end), so in RTL `start` is the right edge\n- `data-orientation` (`vertical` | `horizontal`) on the scrollbars and thumbs\n\nCSS variables on the root, in px (0 while the axis does not overflow): `--scroll-area-overflow-x-start`, `--scroll-area-overflow-x-end`, `--scroll-area-overflow-y-start`, `--scroll-area-overflow-y-end`. Overscroll (WebKit rubber banding) is not counted as hidden content.\n\nThe typed maps `scrollAreaDataAttributes` and `scrollAreaCssVariables` (from `entasis/scroll-area`) list each name with its meaning.\n\n```svelte\n<!-- Rules appear only while content is hidden past that edge. -->\n<ScrollArea class=\"h-64 data-overflow-y-start:border-t data-overflow-y-end:border-b\">\n\tContent\n</ScrollArea>\n```\n\n```css\n/* Fade the top edge only while content is hidden above. */\n[data-scroll-area]::before {\n\topacity: min(1, calc(var(--scroll-area-overflow-y-start) / 24));\n}\n```\n\n## Behavior\n\n- Wheeling over a scrollbar scrolls the viewport, and passes the wheel on to the page once the viewport cannot move that way.\n- Pressing a scrollbar or thumb with the primary button does not move focus (a Combobox input keeps it while its list is dragged). Scroll snapping on the viewport is paused while a thumb is held, then restored.\n- Horizontal scrolling follows the viewport's writing direction: in RTL the offset is negative, the vertical bar sits at the left, the horizontal thumb starts at the right, and the bars inset each other at the corner when both show.\n- While WebKit rubber-bands past either end, the thumb shrinks (down to 18 px) and stays pinned to that edge instead of leaving its track.\n\n## Theme Structure\n\nThe theme object contains:\n- **root**: Main scroll area container styles\n- **viewport**: Scrollable viewport container styles\n- **content**: Scrollable content wrapper styles\n- **scrollbar**: Vertical scrollbar track styles\n- **scrollbarX**: Horizontal scrollbar track styles\n- **scrollbarThumb**: Scrollbar thumb styles\n\n## Available Variants\n\n**viewport**:\n- scrollFade: 'none' | 'y' | 'x' - Adds the shared vertical or horizontal scroll-fade utility\n";

package/dist/components/ScrollArea/scrollArea.mcp.js

@@ -20,9 +20,11 @@ The ScrollArea component provides a native scroll viewport with custom overlay s
 - **ref**: HTMLElement | null (bindable) - Reference to the root scroll-area element
 - **viewportRef**: HTMLElement | null (bindable) - Reference to the native scrolling viewport, suitable for virtualizers and imperative scrolling
 - Native div attributes and attachments are forwarded to the root element
-- **label**: string (default: 'Scrollable content') - Accessible name for the native scrolling viewport
-- **viewportRole**: string (default: 'group') - Role of the scrolling viewport; set it to the role the surrounding structure expects (\`rowgroup\` inside a grid or treegrid, for instance)
-- **type**: 'hover' | 'always' | 'scroll' | 'auto' (default: 'hover') - Controls scrollbar visibility behavior
+- **label**: string - Accessible name for the native scrolling viewport; passing it makes the viewport a named \`group\` even when its content fits. Without it the viewport is named 'Scrollable content' (i18n \`scrollableContent\`) only while it overflows
+- **viewportAttrs**: attributes, handlers and attachments spread onto the scrolling viewport, for a widget that makes the viewport its own element (a listbox: \`role\`, \`aria-activedescendant\`, \`id\`). They win over the viewport's own: \`class\` is added to its classes, and \`onscroll\`, \`onfocus\` and \`onblur\` run before the built-in handling. A \`role\` here hands the viewport's semantics to the caller: the viewport then adds neither the automatic 'Scrollable content' name nor the automatic tab stop, so pass \`tabindex\` and a name when the role needs them
+- **viewportRole**: string - Role of the scrolling viewport. Without it the viewport is a plain element while its content fits and a \`group\` while it overflows (or when \`label\` is passed). Set it to the role the surrounding structure expects (\`rowgroup\` inside a grid or treegrid, for instance); inside a listbox pass \`presentation\`, which keeps the viewport unnamed and out of the tab order even while it overflows
+- **type**: 'hover' | 'always' | 'scroll' | 'auto' (default: 'hover') - Controls scrollbar visibility. \`hover\` shows the bars while the pointer is over the area or the area is scrolling, so touch scrolling (which never hovers) reveals them too; \`always\` and \`auto\` show them whenever the content overflows; \`scroll\` shows them only while scrolling
+- **overflowEdgeThreshold**: number (default: 1) - Px of content that may stay hidden past an edge before \`data-overflow-*-start\` / \`data-overflow-*-end\` (and the \`scrollOnEdges\` arrows) count it
 - **delay**: number (default: 0) - Milliseconds before hover mode treats the area as hovered
 - **onscroll**: (event: Event) => void - Native scroll handler attached to the viewport
 
@@ -66,6 +68,48 @@ The ScrollArea component provides a native scroll viewport with custom overlay s
 - Native browser scrollbars are hidden while custom scrollbar thumbs are rendered over the viewport.
 - Keyboard focus is applied only when the viewport overflows.
 
+## Accessibility
+
+- A viewport whose content fits is a plain element: no role, no name, no tab stop.
+- While it overflows, the viewport is a \`group\` named by \`label\` (default 'Scrollable content') with \`tabindex="0"\`, so keyboard users can scroll it (WCAG SCR34).
+- A focused viewport whose content stops overflowing keeps its role, name and \`tabindex="-1"\` until it blurs, so focus never drops to the page.
+- \`viewportRole="presentation"\` (or \`none\`) keeps the viewport transparent even while it overflows; use it when a surrounding listbox or grid owns keyboard scrolling.
+- The custom scrollbars and the edge-scroll arrows are pointer-only and carry \`aria-hidden="true"\`.
+
+## Styling hooks
+
+Data attributes (presence attributes, set to \`""\` while the state holds):
+
+- \`data-scrolling\` on the root, viewport, scrollbars and thumbs: from the first scroll event until the viewport has been idle for 400 ms
+- \`data-has-overflow-x\` / \`data-has-overflow-y\` on the root: the content overflows on that axis
+- \`data-overflow-x-start\`, \`data-overflow-x-end\`, \`data-overflow-y-start\`, \`data-overflow-y-end\` on the root: content is hidden past that edge by more than \`overflowEdgeThreshold\`. The x edges are logical (inline start / end), so in RTL \`start\` is the right edge
+- \`data-orientation\` (\`vertical\` | \`horizontal\`) on the scrollbars and thumbs
+
+CSS variables on the root, in px (0 while the axis does not overflow): \`--scroll-area-overflow-x-start\`, \`--scroll-area-overflow-x-end\`, \`--scroll-area-overflow-y-start\`, \`--scroll-area-overflow-y-end\`. Overscroll (WebKit rubber banding) is not counted as hidden content.
+
+The typed maps \`scrollAreaDataAttributes\` and \`scrollAreaCssVariables\` (from \`entasis/scroll-area\`) list each name with its meaning.
+
+\`\`\`svelte
+<!-- Rules appear only while content is hidden past that edge. -->
+<ScrollArea class="h-64 data-overflow-y-start:border-t data-overflow-y-end:border-b">
+	Content
+</ScrollArea>
+\`\`\`
+
+\`\`\`css
+/* Fade the top edge only while content is hidden above. */
+[data-scroll-area]::before {
+	opacity: min(1, calc(var(--scroll-area-overflow-y-start) / 24));
+}
+\`\`\`
+
+## Behavior
+
+- Wheeling over a scrollbar scrolls the viewport, and passes the wheel on to the page once the viewport cannot move that way.
+- Pressing a scrollbar or thumb with the primary button does not move focus (a Combobox input keeps it while its list is dragged). Scroll snapping on the viewport is paused while a thumb is held, then restored.
+- Horizontal scrolling follows the viewport's writing direction: in RTL the offset is negative, the vertical bar sits at the left, the horizontal thumb starts at the right, and the bars inset each other at the corner when both show.
+- While WebKit rubber-bands past either end, the thumb shrinks (down to 18 px) and stays pinned to that edge instead of leaving its track.
+
 ## Theme Structure
 
 The theme object contains:

package/dist/components/ScrollArea/scrollArea.props.d.ts

@@ -2,23 +2,43 @@ import type { Snippet } from 'svelte';
 import type { WithAttachments } from '../../types/props.js';
 import type { ScrollAreaThemeProps } from './scrollArea.theme.js';
 import type { HTMLAttributes } from 'svelte/elements';
+/** Attributes, handlers and attachments for the scrolling viewport element. */
+export type ScrollAreaViewportAttributes = WithAttachments<Omit<HTMLAttributes<HTMLDivElement>, 'children'>>;
 type ScrollAreaRootAttributes = Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class' | 'onscroll'>;
 export type ScrollAreaProps = WithAttachments<ScrollAreaRootAttributes & {
     /** Bindable reference to the root scroll-area element. */
     ref?: HTMLDivElement | null;
     /** Bindable reference to the native scrolling viewport. */
     viewportRef?: HTMLDivElement | null;
-    /** Accessible label applied to the native scrolling viewport. */
+    /**
+     * Accessible name of the native scrolling viewport. Passing it makes the viewport a named
+     * `group` even when its content fits. Without it, the viewport is named "Scrollable content"
+     * (from the i18n catalog) only while it overflows and is a keyboard tab stop.
+     */
     label?: string;
     /**
-     * Role of the native scrolling viewport. Override it when the scroll area sits inside a
-     * structural role whose children are constrained — a grid or treegrid, say, where the
-     * viewport has to read as `rowgroup` rather than an unrelated group.
-     * @default 'group'
+     * Role of the native scrolling viewport. Without it, the viewport is a plain element while
+     * its content fits and a `group` while it overflows (or when `label` is passed). Override
+     * it when the scroll area sits inside a structural role whose children are constrained: a
+     * grid or treegrid, say, where the viewport has to read as `rowgroup`. Inside a listbox,
+     * pass `presentation`: the viewport then never takes a name or a tab stop, even while it
+     * overflows, because the listbox owns keyboard scrolling.
      */
     viewportRole?: string;
     /**
-     * Controls when the vertical scrollbar is shown (`hover`, `always`, `scroll`, or `auto`).
+     * Attributes spread onto the scrolling viewport, for a widget that makes the viewport itself
+     * its semantic element: a listbox with `role`, `aria-activedescendant` and its own `id`,
+     * say. They are merged with the viewport's own, and win over them: `class` is added to the
+     * viewport's classes, and `onscroll`, `onfocus` and `onblur` run before the built-in
+     * handling. A `role` here hands the viewport's semantics to the caller: the viewport then
+     * takes neither the automatic "Scrollable content" name nor the automatic tab stop, so pass
+     * `tabindex` (and a name) when the role needs them.
+     */
+    viewportAttrs?: ScrollAreaViewportAttributes;
+    /**
+     * Controls when the scrollbars are shown. `hover` shows them while the pointer is over the
+     * area or the area is scrolling (so touch scrolling, which never hovers, still reveals them),
+     * `always` and `auto` whenever the content overflows, `scroll` only while scrolling.
      * @default 'hover'
      */
     type?: 'auto' | 'always' | 'scroll' | 'hover';
@@ -32,6 +52,13 @@ export type ScrollAreaProps = WithAttachments<ScrollAreaRootAttributes & {
      * @default false
      */
     scrollFade?: boolean;
+    /**
+     * Px of content that may stay hidden past an edge before `data-overflow-*-start` and
+     * `data-overflow-*-end` (and the `scrollOnEdges` arrows) count it. A fractional zoom level
+     * leaves a remainder below one px at the scroll end, which must not read as more content.
+     * @default 1
+     */
+    overflowEdgeThreshold?: number;
     /**
      * Milliseconds to wait before hover mode treats the scroll area as hovered.
      * @default 0

package/dist/components/ScrollArea/scrollArea.svelte.d.ts

@@ -2,6 +2,16 @@ export interface ScrollAreaOptions {
     delay: number;
     type: 'auto' | 'always' | 'scroll' | 'hover';
     scrollOnEdges: boolean;
+    /**
+     * Px of content that may stay hidden past an edge before that edge counts as overflowing.
+     * Defaults to 1.
+     */
+    overflowEdgeThreshold?: number;
+    /**
+     * Writing direction of the viewport. In `rtl` the horizontal offset runs from 0 down to a
+     * negative number, so every horizontal read and write is mirrored. Defaults to `ltr`.
+     */
+    direction?: () => 'ltr' | 'rtl';
 }
 declare const ScrollArea_base: new (props: ScrollAreaOptions) => {} & ScrollAreaOptions;
 export declare class ScrollArea extends ScrollArea_base {
@@ -27,6 +37,18 @@ export declare class ScrollArea extends ScrollArea_base {
     scrollbarXEnabled: boolean;
     visible: boolean;
     visibleX: boolean;
+    rtl: boolean;
+    trackYThickness: number;
+    trackXThickness: number;
+    private edgeThreshold;
+    overflowYStart: number;
+    overflowYEnd: number;
+    overflowXStart: number;
+    overflowXEnd: number;
+    hasOverflowYStart: boolean;
+    hasOverflowYEnd: boolean;
+    hasOverflowXStart: boolean;
+    hasOverflowXEnd: boolean;
     canScrollUp: boolean;
     canScrollDown: boolean;
     thumbRect: {
@@ -37,27 +59,48 @@ export declare class ScrollArea extends ScrollArea_base {
         readonly current: DOMRect;
         reference: (ref: HTMLElement) => (() => void) | undefined;
     };
-    thumbYSize: number;
-    dragY: {
-        readonly reference: ((ref: HTMLElement) => () => void) | null;
-        readonly isDragging: boolean;
+    trackRectX: {
+        readonly current: DOMRect;
+        reference: (ref: HTMLElement) => (() => void) | undefined;
     };
-    isDraggingY: boolean;
+    private trackYLength;
+    private trackXLength;
+    /** Thumb length the content ratio asks for, before any overscroll shrinks it. */
+    thumbYBaseSize: number;
+    thumbXBaseSize: number;
+    overscrollY: number;
+    overscrollX: number;
+    thumbYSize: number;
     thumbXSize: number;
-    dragX: {
-        readonly reference: ((ref: HTMLElement) => () => void) | null;
-        readonly isDragging: boolean;
-    };
+    private savedScrollSnapType;
+    private pauseScrollSnap;
+    private restoreScrollSnap;
+    isDraggingY: boolean;
+    dragY: import("svelte/attachments").Attachment<HTMLElement>;
     isDraggingX: boolean;
-    viewportTabindex: number;
+    dragX: import("svelte/attachments").Attachment<HTMLElement>;
+    overflowing: boolean;
     hoover: {
-        reference: (ref: HTMLElement) => (() => void) | null;
+        reference: (ref: HTMLElement) => () => void;
         destroy: () => void;
+        cancel: () => void;
         readonly isHovered: boolean;
     };
     thumbYPosition: number;
+    /** Distance from the track's inline start to the thumb's inline start edge. */
     thumbXPosition: number;
-    isScrolling: number | null;
+    /** The horizontal thumb's `translateX` in px: mirrored in RTL, where the track fills from the right. */
+    thumbXTranslate: number;
+    isScrolling: boolean;
+    private scrollingTimer;
+    private clearScrollingTimer;
+    /** Horizontal scroll offset as distance from the inline start, whatever the direction. */
+    private readScrollX;
+    /** Scrolls horizontally to a distance from the inline start. */
+    private writeScrollX;
+    /** Re-resolves the writing direction; true when it flipped. */
+    private syncDirection;
+    private readScrollOffsets;
     private handleScroll;
     handleTrackClick: (event: MouseEvent) => void;
     handleTrackClickX: (event: MouseEvent) => void;
@@ -75,6 +118,7 @@ export declare class ScrollArea extends ScrollArea_base {
     viewportAttachment: (element: HTMLElement) => () => void;
     contentAttachment: (element: HTMLElement) => () => void;
     private forwardWheelToViewport;
+    private keepFocusOnPress;
     trackAttachment: (element: HTMLElement) => () => void;
     trackAttachmentX: (element: HTMLElement) => () => void;
     private scrollAnimationFrame;