From e11d3539eff6d6cac93db36f4b87aa0655a19008 Mon Sep 17 00:00:00 2001
From: dev <info@activething.com>
Date: Fri, 22 May 2026 21:24:14 +0200
Subject: [PATCH] feat(scroll-area): add size/radius/scrollbars props + fix
 scroll-type race
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reference-library parity (Radix Themes, Chakra v3):

- size: 'xs' | 'sm' | 'md' | 'lg' (Chakra t-shirt scale) → thickness
  via --scroll-area-scrollbar-size.
- radius: 'none' | 'sm' | 'md' | 'lg' | 'full' (Radix Themes) → thumb
  curvature via --scroll-area-thumb-radius.
- scrollbars: 'vertical' | 'horizontal' | 'both' (Radix Themes) →
  recipe-level sugar that auto-mounts Scrollbar / Thumb / Corner from
  the root. Explicit composition still supported (omit the prop).

Bug fix — type='scroll' + horizontal sometimes stuck hidden:

- `mounted` on ScrollAreaScrollbarProvider is now $state. Previously
  a plain field, so the `shouldShow` derived didn't invalidate when
  the requestFrame mount-flag flipped during the first frame.
- The reveal-on-scroll $effect now skips its first run via a
  `firstRun` flag. That first run was the subscription pass with
  scrollTop/scrollLeft still 0 — it was eagerly calling show() and
  setting `visible=true` before `mounted` flipped. Subsequent real
  scrolls then assigned visible=true again (no-op), so shouldShow
  didn't re-run and the bar stayed hidden until the hide timer
  expired. Now the bar only reveals on genuine scroll deltas.

Demo: chip controls for size + radius, switched to scrollbars prop
on the root (drops the explicit Scrollbar/Thumb children), eidos
snippet shows the recipe-sugar form, soma snippet still shows the
explicit Radix-style composition.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/uix/eidos/components/scroll-area/index.ts |  5 +-
 .../components/scroll-area/scroll-area.svelte | 78 +++++++++++++---
 src/uix/eidos/components/scroll-area/types.ts | 56 +++++++++---
 .../scroll-area-provider.svelte.ts            | 19 +++-
 .../uix/components/scroll-area/+page.svelte   | 89 +++++++++++++------
 5 files changed, 196 insertions(+), 51 deletions(-)

diff --git a/src/uix/eidos/components/scroll-area/index.ts b/src/uix/eidos/components/scroll-area/index.ts
index a8229c0bc..052ef86e3 100644
--- a/src/uix/eidos/components/scroll-area/index.ts
+++ b/src/uix/eidos/components/scroll-area/index.ts
@@ -40,5 +40,8 @@ export type {
 	ScrollAreaScrollbarProps as ScrollbarProps,
 	ScrollAreaThumbProps as ThumbProps,
 	ScrollAreaCornerProps as CornerProps,
-	ScrollAreaType
+	ScrollAreaType,
+	ScrollAreaSize,
+	ScrollAreaRadius,
+	ScrollAreaScrollbars
 } from './types';
diff --git a/src/uix/eidos/components/scroll-area/scroll-area.svelte b/src/uix/eidos/components/scroll-area/scroll-area.svelte
index a702a3d7f..7a22e424c 100644
--- a/src/uix/eidos/components/scroll-area/scroll-area.svelte
+++ b/src/uix/eidos/components/scroll-area/scroll-area.svelte
@@ -1,23 +1,81 @@
 <script lang="ts">
 	/**
 	 * Eidos `<ScrollArea>` — root component. Wraps Soma's
-	 * `<ScrollArea.Provider>` to set up the headless context; children
-	 * compose via the named members attached in `index.ts`:
+	 * `<ScrollArea.Provider>` to set up the headless context.
 	 *
-	 *   <ScrollArea type="hover">
+	 *   <ScrollArea type="hover" size="md" radius="md" scrollbars="vertical">
 	 *     <ScrollArea.Viewport>{content}</ScrollArea.Viewport>
-	 *     <ScrollArea.Scrollbar orientation="vertical">
-	 *       <ScrollArea.Thumb />
-	 *     </ScrollArea.Scrollbar>
-	 *     <ScrollArea.Corner />
 	 *   </ScrollArea>
+	 *
+	 * Two composition modes:
+	 *
+	 * - Explicit (default, Radix-style) — `scrollbars` omitted; user
+	 *   composes Viewport + Scrollbar + Thumb + Corner manually.
+	 * - Sugar (Radix-Themes style) — `scrollbars="vertical|horizontal|both"`
+	 *   auto-mounts the right parts; user only composes Viewport.
+	 *
+	 * `size` / `radius` are pure CSS-variable bindings; they affect
+	 * recipe paint only, not Soma's scroll math.
 	 */
 	import * as ScrollArea from '$soma/components/scroll-area';
-	import type { ScrollAreaProps } from './types';
+	import Viewport from './scroll-area-viewport.svelte';
+	import Scrollbar from './scroll-area-scrollbar.svelte';
+	import Thumb from './scroll-area-thumb.svelte';
+	import Corner from './scroll-area-corner.svelte';
+	import type { ScrollAreaProps, ScrollAreaSize, ScrollAreaRadius } from './types';
+
+	let {
+		children,
+		size,
+		radius,
+		scrollbars,
+		style,
+		...rest
+	}: ScrollAreaProps = $props();
+
+	// Map t-shirt size → `--space-*` token. Matches Chakra's xs/sm/md/lg
+	// scale. The CSS recipe consumes `--scroll-area-scrollbar-size` for
+	// both track thickness and corner dimensions.
+	const SIZE_TOKEN: Record<ScrollAreaSize, string> = {
+		xs: 'var(--space-1-5)',
+		sm: 'var(--space-2)',
+		md: 'var(--space-2-5)',
+		lg: 'var(--space-3)'
+	};
+
+	const RADIUS_TOKEN: Record<ScrollAreaRadius, string> = {
+		none: '0',
+		sm: 'var(--radius-sm)',
+		md: 'var(--radius-md)',
+		lg: 'var(--radius-lg)',
+		full: 'var(--radius-full)'
+	};
+
+	const recipeStyle = $derived(() => {
+		const parts: string[] = [];
+		if (size) parts.push(`--scroll-area-scrollbar-size: ${SIZE_TOKEN[size]};`);
+		if (radius) parts.push(`--scroll-area-thumb-radius: ${RADIUS_TOKEN[radius]};`);
+		return parts.join(' ');
+	});
 
-	let { children, ...rest }: ScrollAreaProps = $props();
+	const mergedStyle = $derived(
+		[recipeStyle(), typeof style === 'string' ? style : ''].filter(Boolean).join(' ')
+	);
 </script>
 
-<ScrollArea.Provider {...rest}>
+<ScrollArea.Provider {...rest} style={mergedStyle || undefined}>
 	{@render children?.()}
+	{#if scrollbars === 'vertical' || scrollbars === 'both'}
+		<Scrollbar orientation="vertical">
+			<Thumb />
+		</Scrollbar>
+	{/if}
+	{#if scrollbars === 'horizontal' || scrollbars === 'both'}
+		<Scrollbar orientation="horizontal">
+			<Thumb />
+		</Scrollbar>
+	{/if}
+	{#if scrollbars === 'both'}
+		<Corner />
+	{/if}
 </ScrollArea.Provider>
diff --git a/src/uix/eidos/components/scroll-area/types.ts b/src/uix/eidos/components/scroll-area/types.ts
index d56a8ff92..0705211e3 100644
--- a/src/uix/eidos/components/scroll-area/types.ts
+++ b/src/uix/eidos/components/scroll-area/types.ts
@@ -10,28 +10,62 @@ import type {
 /**
  * Eidos ScrollArea types.
  *
- * Compound shape mirrors Radix Primitives:
+ * Compound shape mirrors Radix Primitives, with three recipe-level
+ * sugar props promoted on the root (`size`, `radius`, `scrollbars`)
+ * that match Radix Themes / Chakra UI conventions:
  *
+ *   <ScrollArea size="md" radius="md" scrollbars="vertical">
+ *     <ScrollArea.Viewport>{content}</ScrollArea.Viewport>
+ *   </ScrollArea>
+ *
+ *   <!-- Full explicit composition (default; `scrollbars` omitted) -->
  *   <ScrollArea>
  *     <ScrollArea.Viewport>{content}</ScrollArea.Viewport>
  *     <ScrollArea.Scrollbar orientation="vertical">
  *       <ScrollArea.Thumb />
  *     </ScrollArea.Scrollbar>
- *     <ScrollArea.Scrollbar orientation="horizontal">
- *       <ScrollArea.Thumb />
- *     </ScrollArea.Scrollbar>
  *     <ScrollArea.Corner />
  *   </ScrollArea>
  *
- * Eidos adds no evaluative props — geometry and scrollbar timing live
- * fully in the Soma headless layer. The recipe consumes the
- * `data-state` / `data-orientation` markers emitted by the morfo
- * runtime so visibility transitions and orientation swaps require no
- * additional wiring from Eidos.
+ * Soma still owns geometry + timer; Eidos adds size / radius / axis
+ * sugar on top.
+ */
+
+/** Scrollbar thickness — t-shirt scale (Chakra-style). Maps to a `--space-*` token. */
+export type ScrollAreaSize = 'xs' | 'sm' | 'md' | 'lg';
+
+/** Thumb / corner radius — maps to a `--radius-*` token. */
+export type ScrollAreaRadius = 'none' | 'sm' | 'md' | 'lg' | 'full';
+
+/**
+ * Which scrollbars the recipe auto-mounts. When set, the user does
+ * NOT compose `<ScrollArea.Scrollbar>` / `<ScrollArea.Thumb>` /
+ * `<ScrollArea.Corner>` manually — the root wires them. Leave
+ * undefined for the canonical Radix-style explicit composition.
+ *
+ * Mirrors Radix Themes' `scrollbars` prop.
  */
+export type ScrollAreaScrollbars = 'vertical' | 'horizontal' | 'both';
 
-/** Props for the `<ScrollArea>` root. Pass-through from headless. */
-export type ScrollAreaProps = ProviderProps;
+/** Props for the `<ScrollArea>` root. Soma props + eidos recipe sugar. */
+export type ScrollAreaProps = ProviderProps & {
+	/**
+	 * Scrollbar thickness. Maps to `--scroll-area-scrollbar-size`.
+	 * @default 'md'
+	 */
+	size?: ScrollAreaSize;
+	/**
+	 * Thumb / corner radius. Maps to `--scroll-area-thumb-radius`.
+	 * @default 'full'
+	 */
+	radius?: ScrollAreaRadius;
+	/**
+	 * Which scrollbars the recipe auto-mounts. When omitted, the user
+	 * composes Scrollbar / Thumb / Corner parts manually inside
+	 * `children` (Radix Primitives style).
+	 */
+	scrollbars?: ScrollAreaScrollbars;
+};
 /** Props for `<ScrollArea.Viewport>`. Pass-through from headless. */
 export type ScrollAreaViewportProps = ViewportProps;
 /** Props for `<ScrollArea.Scrollbar>`. Pass-through from headless. */
diff --git a/src/uix/soma/components/scroll-area/scroll-area-provider.svelte.ts b/src/uix/soma/components/scroll-area/scroll-area-provider.svelte.ts
index 88d2534a0..cac5f254b 100644
--- a/src/uix/soma/components/scroll-area/scroll-area-provider.svelte.ts
+++ b/src/uix/soma/components/scroll-area/scroll-area-provider.svelte.ts
@@ -230,7 +230,12 @@ export class ScrollAreaScrollbarProvider {
 	// Visibility state
 	visible = $state(false);
 	private hideTimer: TimerHandle | null = null;
-	private mounted = false;
+	// `mounted` MUST be reactive — `shouldShow` reads it to suppress the
+	// initial-mount flash, so flipping it from false→true during the
+	// first frame has to invalidate the derived. Without `$state` the
+	// derived caches the false value and `visible` flips inside the
+	// `shouldShow` derivation lose the race.
+	private mounted = $state(false);
 	hovering = $state(false);
 	dragging = $state(false);
 
@@ -259,10 +264,20 @@ export class ScrollAreaScrollbarProvider {
 		});
 
 		// Reveal the scrollbar on parent scroll for 'scroll' and 'hover' types.
-		// Previously lived in the wrapper as an ad-hoc effect.
+		// The first run of an `$effect` is a subscription-setup pass, not a real
+		// scroll event — without the `firstRun` guard the initial run would call
+		// `show()` immediately, setting `visible=true` before `mounted` flips.
+		// Subsequent real-scroll runs would then see `visible` already at `true`
+		// and the no-op assignment wouldn't invalidate `shouldShow`, leaving the
+		// bar stuck hidden until the hide timer expired.
+		let firstRun = true;
 		$effect(() => {
 			void this.provider.scrollTop;
 			void this.provider.scrollLeft;
+			if (firstRun) {
+				firstRun = false;
+				return;
+			}
 			const type = this.provider.opts.type.current;
 			if (type === 'scroll' || type === 'hover') {
 				this.show();
diff --git a/web/routes/uix/components/scroll-area/+page.svelte b/web/routes/uix/components/scroll-area/+page.svelte
index 25f7435c7..641c5ad4e 100644
--- a/web/routes/uix/components/scroll-area/+page.svelte
+++ b/web/routes/uix/components/scroll-area/+page.svelte
@@ -2,7 +2,10 @@
 	import {
 		ScrollArea,
 		type ScrollAreaProps,
-		type ScrollAreaType
+		type ScrollAreaType,
+		type ScrollAreaSize,
+		type ScrollAreaRadius,
+		type ScrollAreaScrollbars
 	} from '$uix/eidos/components/scroll-area';
 	import { compileMorfo } from '$uix/morfo';
 	import { scrollAreaMorfo } from '@/uix/morfo/components/scroll-area';
@@ -17,14 +20,23 @@
 	const types: ScrollAreaType[] = ['hover', 'scroll', 'auto', 'always'];
 	let type = $state<ScrollAreaType>('hover');
 	let scrollHideDelay = $state<number>(600);
-	type Axis = 'vertical' | 'horizontal' | 'both';
-	const axes = ['vertical', 'horizontal', 'both'] as const;
+
+	const sizes: ScrollAreaSize[] = ['xs', 'sm', 'md', 'lg'];
+	let size = $state<ScrollAreaSize>('md');
+
+	const radii: ScrollAreaRadius[] = ['none', 'sm', 'md', 'lg', 'full'];
+	let radius = $state<ScrollAreaRadius>('full');
+
+	type Axis = ScrollAreaScrollbars;
+	const axes: Axis[] = ['vertical', 'horizontal', 'both'];
 	let axis = $state<Axis>('vertical');
 	let itemCount = $state<number>(40);
 
 	const areaProps = $derived<Partial<ScrollAreaProps>>({
 		type,
-		scrollHideDelay
+		scrollHideDelay,
+		size,
+		radius
 	});
 
 	// ── Compiled morfo ───────────────────────────────────────────────────
@@ -61,6 +73,8 @@
 	);
 
 	// ── Snippets ─────────────────────────────────────────────────────────
+	// Soma is headless — no `size` / `radius` / `scrollbars` sugar; the user
+	// composes Scrollbar / Thumb / Corner parts directly.
 	const somaSnippet = $derived(
 		[
 			"<script lang='ts'>",
@@ -77,7 +91,8 @@
 			(axis === 'vertical' || axis === 'both') && '  <ScrollArea.Scrollbar orientation="vertical">',
 			(axis === 'vertical' || axis === 'both') && '    <ScrollArea.Thumb />',
 			(axis === 'vertical' || axis === 'both') && '  </ScrollArea.Scrollbar>',
-			(axis === 'horizontal' || axis === 'both') && '  <ScrollArea.Scrollbar orientation="horizontal">',
+			(axis === 'horizontal' || axis === 'both') &&
+				'  <ScrollArea.Scrollbar orientation="horizontal">',
 			(axis === 'horizontal' || axis === 'both') && '    <ScrollArea.Thumb />',
 			(axis === 'horizontal' || axis === 'both') && '  </ScrollArea.Scrollbar>',
 			axis === 'both' && '  <ScrollArea.Corner />',
@@ -87,6 +102,9 @@
 			.join('\n')
 	);
 
+	// Eidos exposes `size` / `radius` / `scrollbars` sugar. With
+	// `scrollbars` set, the recipe auto-mounts Scrollbar / Thumb /
+	// Corner parts — children carry only the Viewport.
 	const eidosSnippet = $derived(
 		[
 			"<script lang='ts'>",
@@ -96,17 +114,13 @@
 			'<ScrollArea',
 			type !== 'hover' && `  type="${type}"`,
 			scrollHideDelay !== 600 && `  scrollHideDelay={${scrollHideDelay}}`,
+			size !== 'md' && `  size="${size}"`,
+			radius !== 'full' && `  radius="${radius}"`,
+			`  scrollbars="${axis}"`,
 			'>',
 			'  <ScrollArea.Viewport>',
 			'    <!-- scrollable content -->',
 			'  </ScrollArea.Viewport>',
-			(axis === 'vertical' || axis === 'both') && '  <ScrollArea.Scrollbar orientation="vertical">',
-			(axis === 'vertical' || axis === 'both') && '    <ScrollArea.Thumb />',
-			(axis === 'vertical' || axis === 'both') && '  </ScrollArea.Scrollbar>',
-			(axis === 'horizontal' || axis === 'both') && '  <ScrollArea.Scrollbar orientation="horizontal">',
-			(axis === 'horizontal' || axis === 'both') && '    <ScrollArea.Thumb />',
-			(axis === 'horizontal' || axis === 'both') && '  </ScrollArea.Scrollbar>',
-			axis === 'both' && '  <ScrollArea.Corner />',
 			'</ScrollArea>'
 		]
 			.filter(Boolean)
@@ -148,7 +162,7 @@
 			<div
 				style="inline-size: 100%; max-inline-size: 32rem; block-size: 16rem; border: 1px solid var(--color-border-default); border-radius: var(--radius-md); background: var(--color-surface-default); overflow: hidden;"
 			>
-				<ScrollArea {...areaProps} style="inline-size: 100%; block-size: 100%;">
+				<ScrollArea {...areaProps} scrollbars={axis} style="inline-size: 100%; block-size: 100%;">
 					<ScrollArea.Viewport style="inline-size: 100%; block-size: 100%;">
 						<div
 							style={`padding: var(--space-4); ${axis === 'horizontal' || axis === 'both' ? 'inline-size: 48rem;' : ''}`}
@@ -172,19 +186,6 @@
 							</ul>
 						</div>
 					</ScrollArea.Viewport>
-					{#if axis === 'vertical' || axis === 'both'}
-						<ScrollArea.Scrollbar orientation="vertical">
-							<ScrollArea.Thumb />
-						</ScrollArea.Scrollbar>
-					{/if}
-					{#if axis === 'horizontal' || axis === 'both'}
-						<ScrollArea.Scrollbar orientation="horizontal">
-							<ScrollArea.Thumb />
-						</ScrollArea.Scrollbar>
-					{/if}
-					{#if axis === 'both'}
-						<ScrollArea.Corner />
-					{/if}
 				</ScrollArea>
 			</div>
 		</div>
@@ -252,10 +253,44 @@
 				</label>
 			</div>
 
+			<div data-uix-subsection-head>
+				<span data-uix-layer-badge="eidos">eidos</span> props · recipe sugar
+			</div>
+			<div data-uix-controls>
+				<label data-uix-control>
+					<span data-uix-control-label
+						>size <span data-uix-control-hint>scrollbar thickness (Chakra-style)</span></span
+					>
+					<span data-uix-chips role="radiogroup">
+						{#each sizes as opt}
+							<button data-uix-chip data-active={size === opt} onclick={() => (size = opt)}
+								>{opt}</button
+							>
+						{/each}
+					</span>
+				</label>
+				<label data-uix-control>
+					<span data-uix-control-label
+						>radius <span data-uix-control-hint>thumb curvature</span></span
+					>
+					<span data-uix-chips role="radiogroup">
+						{#each radii as opt}
+							<button data-uix-chip data-active={radius === opt} onclick={() => (radius = opt)}
+								>{opt}</button
+							>
+						{/each}
+					</span>
+				</label>
+			</div>
+
 			<div data-uix-subsection-head>Composition · which scrollbars to mount</div>
 			<div data-uix-controls>
 				<label data-uix-control>
-					<span data-uix-control-label>axis</span>
+					<span data-uix-control-label
+						>scrollbars <span data-uix-control-hint
+							>axes auto-mounted by the recipe (Radix Themes-style sugar)</span
+						></span
+					>
 					<span data-uix-chips role="radiogroup">
 						{#each axes as opt}
 							<button data-uix-chip data-active={axis === opt} onclick={() => (axis = opt)}