@lattice-ui/scroll-area 0.3.0

package/README.md

@@ -0,0 +1,18 @@
+# @lattice-ui/scroll-area
+
+Headless scroll area primitives for Roblox UI with custom scrollbars and thumbs.
+
+## Exports
+
+- `ScrollArea`
+- `ScrollArea.Root`
+- `ScrollArea.Viewport`
+- `ScrollArea.Scrollbar`
+- `ScrollArea.Thumb`
+- `ScrollArea.Corner`
+
+## Notes
+
+- Supports vertical and horizontal scrollbar primitives.
+- `type` supports `auto`, `always`, and `scroll` visibility policies.
+- Thumb/canvas math helpers are exported for unit testing.

package/out/ScrollArea/ScrollAreaCorner.d.ts

@@ -0,0 +1,3 @@
+import { React } from "@lattice-ui/core";
+import type { ScrollAreaCornerProps } from "./types";
+export declare function ScrollAreaCorner(props: ScrollAreaCornerProps): React.JSX.Element;

package/out/ScrollArea/ScrollAreaCorner.luau

@@ -0,0 +1,29 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _core = TS.import(script, TS.getModule(script, "@lattice-ui", "core").out)
+local React = _core.React
+local Slot = _core.Slot
+local useScrollAreaContext = TS.import(script, script.Parent, "context").useScrollAreaContext
+local function ScrollAreaCorner(props)
+	local scrollAreaContext = useScrollAreaContext()
+	local visible = scrollAreaContext.showHorizontalScrollbar and scrollAreaContext.showVerticalScrollbar
+	if props.asChild then
+		local child = props.children
+		if not child then
+			error("[ScrollAreaCorner] `asChild` requires a child element.")
+		end
+		return React.createElement(Slot, {
+			Visible = visible,
+		}, child)
+	end
+	return React.createElement("frame", {
+		BackgroundColor3 = Color3.fromRGB(44, 52, 67),
+		BorderSizePixel = 0,
+		Position = UDim2.fromScale(1, 1),
+		Size = UDim2.fromOffset(8, 8),
+		Visible = visible,
+	}, props.children)
+end
+return {
+	ScrollAreaCorner = ScrollAreaCorner,
+}

package/out/ScrollArea/ScrollAreaRoot.d.ts

@@ -0,0 +1,4 @@
+import { React } from "@lattice-ui/core";
+import type { ScrollAreaProps } from "./types";
+export declare function ScrollAreaRoot(props: ScrollAreaProps): React.JSX.Element;
+export { ScrollAreaRoot as ScrollArea };

package/out/ScrollArea/ScrollAreaRoot.luau

@@ -0,0 +1,75 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local React = TS.import(script, TS.getModule(script, "@lattice-ui", "core").out).React
+local ScrollAreaContextProvider = TS.import(script, script.Parent, "context").ScrollAreaContextProvider
+local function createAxisMetrics()
+	return {
+		viewportSize = 0,
+		contentSize = 0,
+		scrollPosition = 0,
+	}
+end
+local function ScrollAreaRoot(props)
+	local scrollType = props.type or "auto"
+	local _condition = props.scrollHideDelayMs
+	if _condition == nil then
+		_condition = 600
+	end
+	local scrollHideDelayMs = math.max(0, _condition)
+	local viewportRef = React.useRef()
+	local metrics, setMetrics = React.useState(function()
+		return {
+			vertical = createAxisMetrics(),
+			horizontal = createAxisMetrics(),
+		}
+	end)
+	local showScrollbarsFromActivity, setShowScrollbarsFromActivity = React.useState(scrollType ~= "scroll")
+	local activitySequenceRef = React.useRef(0)
+	React.useEffect(function()
+		if scrollType ~= "scroll" then
+			setShowScrollbarsFromActivity(true)
+		end
+	end, { scrollType })
+	local setViewport = React.useCallback(function(instance)
+		viewportRef.current = instance
+	end, {})
+	local notifyScrollActivity = React.useCallback(function()
+		if scrollType ~= "scroll" then
+			return nil
+		end
+		activitySequenceRef.current += 1
+		local sequence = activitySequenceRef.current
+		setShowScrollbarsFromActivity(true)
+		task.delay(scrollHideDelayMs / 1000, function()
+			if sequence ~= activitySequenceRef.current then
+				return nil
+			end
+			setShowScrollbarsFromActivity(false)
+		end)
+	end, { scrollHideDelayMs, scrollType })
+	local hasVerticalOverflow = metrics.vertical.contentSize > metrics.vertical.viewportSize + 1
+	local hasHorizontalOverflow = metrics.horizontal.contentSize > metrics.horizontal.viewportSize + 1
+	local showVerticalScrollbar = if scrollType == "always" then hasVerticalOverflow elseif scrollType == "scroll" then hasVerticalOverflow and showScrollbarsFromActivity else hasVerticalOverflow
+	local showHorizontalScrollbar = if scrollType == "always" then hasHorizontalOverflow elseif scrollType == "scroll" then hasHorizontalOverflow and showScrollbarsFromActivity else hasHorizontalOverflow
+	local contextValue = React.useMemo(function()
+		return {
+			type = scrollType,
+			scrollHideDelayMs = scrollHideDelayMs,
+			viewportRef = viewportRef,
+			setViewport = setViewport,
+			vertical = metrics.vertical,
+			horizontal = metrics.horizontal,
+			setMetrics = setMetrics,
+			notifyScrollActivity = notifyScrollActivity,
+			showVerticalScrollbar = showVerticalScrollbar,
+			showHorizontalScrollbar = showHorizontalScrollbar,
+		}
+	end, { metrics.horizontal, metrics.vertical, notifyScrollActivity, scrollHideDelayMs, setViewport, showHorizontalScrollbar, showVerticalScrollbar, scrollType })
+	return React.createElement(ScrollAreaContextProvider, {
+		value = contextValue,
+	}, props.children)
+end
+return {
+	ScrollAreaRoot = ScrollAreaRoot,
+	ScrollArea = ScrollAreaRoot,
+}

package/out/ScrollArea/ScrollAreaScrollbar.d.ts

@@ -0,0 +1,3 @@
+import { React } from "@lattice-ui/core";
+import type { ScrollAreaScrollbarProps } from "./types";
+export declare function ScrollAreaScrollbar(props: ScrollAreaScrollbarProps): React.JSX.Element;

package/out/ScrollArea/ScrollAreaScrollbar.luau

@@ -0,0 +1,30 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _core = TS.import(script, TS.getModule(script, "@lattice-ui", "core").out)
+local React = _core.React
+local Slot = _core.Slot
+local useScrollAreaContext = TS.import(script, script.Parent, "context").useScrollAreaContext
+local function ScrollAreaScrollbar(props)
+	local scrollAreaContext = useScrollAreaContext()
+	local vertical = props.orientation == "vertical"
+	local visible = if vertical then scrollAreaContext.showVerticalScrollbar else scrollAreaContext.showHorizontalScrollbar
+	if props.asChild then
+		local child = props.children
+		if not child then
+			error("[ScrollAreaScrollbar] `asChild` requires a child element.")
+		end
+		return React.createElement(Slot, {
+			Visible = visible,
+		}, child)
+	end
+	return React.createElement("frame", {
+		BackgroundColor3 = Color3.fromRGB(44, 52, 67),
+		BorderSizePixel = 0,
+		Position = if vertical then UDim2.fromScale(1, 0) else UDim2.fromScale(0, 1),
+		Size = if vertical then UDim2.fromOffset(8, 160) else UDim2.fromOffset(260, 8),
+		Visible = visible,
+	}, props.children)
+end
+return {
+	ScrollAreaScrollbar = ScrollAreaScrollbar,
+}

package/out/ScrollArea/ScrollAreaThumb.d.ts

@@ -0,0 +1,3 @@
+import { React } from "@lattice-ui/core";
+import type { ScrollAreaThumbProps } from "./types";
+export declare function ScrollAreaThumb(props: ScrollAreaThumbProps): React.JSX.Element;

package/out/ScrollArea/ScrollAreaThumb.luau

@@ -0,0 +1,40 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _core = TS.import(script, TS.getModule(script, "@lattice-ui", "core").out)
+local React = _core.React
+local Slot = _core.Slot
+local useScrollAreaContext = TS.import(script, script.Parent, "context").useScrollAreaContext
+local _scrollMath = TS.import(script, script.Parent, "scrollMath")
+local resolveThumbOffset = _scrollMath.resolveThumbOffset
+local resolveThumbSize = _scrollMath.resolveThumbSize
+local function ScrollAreaThumb(props)
+	local scrollAreaContext = useScrollAreaContext()
+	local vertical = props.orientation == "vertical"
+	local axisMetrics = if vertical then scrollAreaContext.vertical else scrollAreaContext.horizontal
+	local trackSize = math.max(1, axisMetrics.viewportSize)
+	local thumbSize = resolveThumbSize(axisMetrics.viewportSize, axisMetrics.contentSize, trackSize)
+	local thumbOffset = resolveThumbOffset(axisMetrics.scrollPosition, axisMetrics.viewportSize, axisMetrics.contentSize, trackSize, thumbSize)
+	local sizeScale = if trackSize > 0 then thumbSize / trackSize else 1
+	local offsetScale = if trackSize > 0 then thumbOffset / trackSize else 0
+	if props.asChild then
+		local child = props.children
+		if not child then
+			error("[ScrollAreaThumb] `asChild` requires a child element.")
+		end
+		return React.createElement(Slot, {
+			Position = if vertical then UDim2.fromScale(0, offsetScale) else UDim2.fromScale(offsetScale, 0),
+			Size = if vertical then UDim2.fromScale(1, sizeScale) else UDim2.fromScale(sizeScale, 1),
+		}, child)
+	end
+	return React.createElement("frame", {
+		BackgroundColor3 = Color3.fromRGB(118, 128, 149),
+		BorderSizePixel = 0,
+		Position = if vertical then UDim2.fromScale(0, offsetScale) else UDim2.fromScale(offsetScale, 0),
+		Size = if vertical then UDim2.fromScale(1, sizeScale) else UDim2.fromScale(sizeScale, 1),
+	}, React.createElement("uicorner", {
+		CornerRadius = UDim.new(1, 0),
+	}), props.children)
+end
+return {
+	ScrollAreaThumb = ScrollAreaThumb,
+}

package/out/ScrollArea/ScrollAreaViewport.d.ts

@@ -0,0 +1,3 @@
+import { React } from "@lattice-ui/core";
+import type { ScrollAreaViewportProps } from "./types";
+export declare function ScrollAreaViewport(props: ScrollAreaViewportProps): React.JSX.Element;

package/out/ScrollArea/ScrollAreaViewport.luau

@@ -0,0 +1,74 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _core = TS.import(script, TS.getModule(script, "@lattice-ui", "core").out)
+local React = _core.React
+local Slot = _core.Slot
+local useScrollAreaContext = TS.import(script, script.Parent, "context").useScrollAreaContext
+local function toScrollingFrame(instance)
+	if not instance or not instance:IsA("ScrollingFrame") then
+		return nil
+	end
+	return instance
+end
+local function ScrollAreaViewport(props)
+	local scrollAreaContext = useScrollAreaContext()
+	local setViewportRef = React.useCallback(function(instance)
+		scrollAreaContext.setViewport(toScrollingFrame(instance))
+	end, { scrollAreaContext })
+	React.useEffect(function()
+		local viewport = scrollAreaContext.viewportRef.current
+		if not viewport then
+			return nil
+		end
+		local updateMetrics = function()
+			scrollAreaContext.setMetrics({
+				vertical = {
+					viewportSize = viewport.AbsoluteWindowSize.Y,
+					contentSize = viewport.AbsoluteCanvasSize.Y,
+					scrollPosition = viewport.CanvasPosition.Y,
+				},
+				horizontal = {
+					viewportSize = viewport.AbsoluteWindowSize.X,
+					contentSize = viewport.AbsoluteCanvasSize.X,
+					scrollPosition = viewport.CanvasPosition.X,
+				},
+			})
+		end
+		updateMetrics()
+		local canvasConnection = viewport:GetPropertyChangedSignal("CanvasPosition"):Connect(function()
+			updateMetrics()
+			scrollAreaContext.notifyScrollActivity()
+		end)
+		local absoluteCanvasConnection = viewport:GetPropertyChangedSignal("AbsoluteCanvasSize"):Connect(updateMetrics)
+		local absoluteWindowConnection = viewport:GetPropertyChangedSignal("AbsoluteWindowSize"):Connect(updateMetrics)
+		return function()
+			canvasConnection:Disconnect()
+			absoluteCanvasConnection:Disconnect()
+			absoluteWindowConnection:Disconnect()
+		end
+	end, { scrollAreaContext })
+	if props.asChild then
+		local child = props.children
+		if not child then
+			error("[ScrollAreaViewport] `asChild` requires a child element.")
+		end
+		return React.createElement(Slot, {
+			ref = setViewportRef,
+		}, child)
+	end
+	return React.createElement("scrollingframe", {
+		Active = true,
+		AutomaticCanvasSize = Enum.AutomaticSize.XY,
+		BackgroundTransparency = 1,
+		BorderSizePixel = 0,
+		CanvasSize = UDim2.fromScale(0, 0),
+		ScrollBarImageTransparency = 1,
+		ScrollBarThickness = 0,
+		ScrollingDirection = Enum.ScrollingDirection.XY,
+		Size = UDim2.fromOffset(260, 160),
+		ref = setViewportRef,
+	}, props.children)
+end
+return {
+	ScrollAreaViewport = ScrollAreaViewport,
+}

package/out/ScrollArea/context.d.ts

@@ -0,0 +1,3 @@
+import type { ScrollAreaContextValue } from "./types";
+declare const ScrollAreaContextProvider: import("@rbxts/react").Provider<ScrollAreaContextValue | undefined>, useScrollAreaContext: () => ScrollAreaContextValue;
+export { ScrollAreaContextProvider, useScrollAreaContext };

package/out/ScrollArea/context.luau

@@ -0,0 +1,10 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local createStrictContext = TS.import(script, TS.getModule(script, "@lattice-ui", "core").out).createStrictContext
+local _binding = createStrictContext("ScrollArea")
+local ScrollAreaContextProvider = _binding[1]
+local useScrollAreaContext = _binding[2]
+return {
+	ScrollAreaContextProvider = ScrollAreaContextProvider,
+	useScrollAreaContext = useScrollAreaContext,
+}

package/out/ScrollArea/scrollMath.d.ts

@@ -0,0 +1,3 @@
+export declare function resolveThumbSize(viewportSize: number, contentSize: number, trackSize: number, minimumThumbSize?: number): number;
+export declare function resolveThumbOffset(scrollPosition: number, viewportSize: number, contentSize: number, trackSize: number, thumbSize: number): number;
+export declare function resolveCanvasPositionFromThumbOffset(thumbOffset: number, viewportSize: number, contentSize: number, trackSize: number, thumbSize: number): number;

package/out/ScrollArea/scrollMath.luau

@@ -0,0 +1,36 @@
+-- Compiled with roblox-ts v3.0.0
+local function resolveThumbSize(viewportSize, contentSize, trackSize, minimumThumbSize)
+	if minimumThumbSize == nil then
+		minimumThumbSize = 18
+	end
+	if viewportSize <= 0 or contentSize <= 0 or trackSize <= 0 then
+		return minimumThumbSize
+	end
+	if contentSize <= viewportSize then
+		return trackSize
+	end
+	local proportionalSize = (viewportSize / contentSize) * trackSize
+	return math.clamp(proportionalSize, minimumThumbSize, trackSize)
+end
+local function resolveThumbOffset(scrollPosition, viewportSize, contentSize, trackSize, thumbSize)
+	if contentSize <= viewportSize or trackSize <= thumbSize then
+		return 0
+	end
+	local maxScroll = math.max(1, contentSize - viewportSize)
+	local maxThumbOffset = trackSize - thumbSize
+	return math.clamp((scrollPosition / maxScroll) * maxThumbOffset, 0, maxThumbOffset)
+end
+local function resolveCanvasPositionFromThumbOffset(thumbOffset, viewportSize, contentSize, trackSize, thumbSize)
+	if contentSize <= viewportSize or trackSize <= thumbSize then
+		return 0
+	end
+	local maxScroll = math.max(1, contentSize - viewportSize)
+	local maxThumbOffset = trackSize - thumbSize
+	local ratio = math.clamp(thumbOffset / maxThumbOffset, 0, 1)
+	return ratio * maxScroll
+end
+return {
+	resolveThumbSize = resolveThumbSize,
+	resolveThumbOffset = resolveThumbOffset,
+	resolveCanvasPositionFromThumbOffset = resolveCanvasPositionFromThumbOffset,
+}

package/out/ScrollArea/types.d.ts

@@ -0,0 +1,46 @@
+import type React from "@rbxts/react";
+export type ScrollAreaType = "auto" | "always" | "scroll";
+export type ScrollAreaOrientation = "vertical" | "horizontal";
+export type ScrollAxisMetrics = {
+    viewportSize: number;
+    contentSize: number;
+    scrollPosition: number;
+};
+export type ScrollAreaContextValue = {
+    type: ScrollAreaType;
+    scrollHideDelayMs: number;
+    viewportRef: React.MutableRefObject<ScrollingFrame | undefined>;
+    setViewport: (instance: ScrollingFrame | undefined) => void;
+    vertical: ScrollAxisMetrics;
+    horizontal: ScrollAxisMetrics;
+    setMetrics: (metrics: {
+        vertical: ScrollAxisMetrics;
+        horizontal: ScrollAxisMetrics;
+    }) => void;
+    notifyScrollActivity: () => void;
+    showVerticalScrollbar: boolean;
+    showHorizontalScrollbar: boolean;
+};
+export type ScrollAreaProps = {
+    type?: ScrollAreaType;
+    scrollHideDelayMs?: number;
+    children?: React.ReactNode;
+};
+export type ScrollAreaViewportProps = {
+    asChild?: boolean;
+    children?: React.ReactElement;
+};
+export type ScrollAreaScrollbarProps = {
+    orientation: ScrollAreaOrientation;
+    asChild?: boolean;
+    children?: React.ReactElement;
+};
+export type ScrollAreaThumbProps = {
+    orientation: ScrollAreaOrientation;
+    asChild?: boolean;
+    children?: React.ReactElement;
+};
+export type ScrollAreaCornerProps = {
+    asChild?: boolean;
+    children?: React.ReactElement;
+};

package/out/ScrollArea/types.luau

@@ -0,0 +1,2 @@
+-- Compiled with roblox-ts v3.0.0
+return nil

package/out/index.d.ts

@@ -0,0 +1,14 @@
+import { ScrollAreaCorner } from "./ScrollArea/ScrollAreaCorner";
+import { ScrollAreaRoot } from "./ScrollArea/ScrollAreaRoot";
+import { ScrollAreaScrollbar } from "./ScrollArea/ScrollAreaScrollbar";
+import { ScrollAreaThumb } from "./ScrollArea/ScrollAreaThumb";
+import { ScrollAreaViewport } from "./ScrollArea/ScrollAreaViewport";
+export declare const ScrollArea: {
+    readonly Root: typeof ScrollAreaRoot;
+    readonly Viewport: typeof ScrollAreaViewport;
+    readonly Scrollbar: typeof ScrollAreaScrollbar;
+    readonly Thumb: typeof ScrollAreaThumb;
+    readonly Corner: typeof ScrollAreaCorner;
+};
+export { resolveCanvasPositionFromThumbOffset, resolveThumbOffset, resolveThumbSize } from "./ScrollArea/scrollMath";
+export type { ScrollAreaContextValue, ScrollAreaCornerProps, ScrollAreaOrientation, ScrollAreaProps, ScrollAreaScrollbarProps, ScrollAreaThumbProps, ScrollAreaType, ScrollAreaViewportProps, ScrollAxisMetrics, } from "./ScrollArea/types";

package/out/init.luau

@@ -0,0 +1,21 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local exports = {}
+local ScrollAreaCorner = TS.import(script, script, "ScrollArea", "ScrollAreaCorner").ScrollAreaCorner
+local ScrollAreaRoot = TS.import(script, script, "ScrollArea", "ScrollAreaRoot").ScrollAreaRoot
+local ScrollAreaScrollbar = TS.import(script, script, "ScrollArea", "ScrollAreaScrollbar").ScrollAreaScrollbar
+local ScrollAreaThumb = TS.import(script, script, "ScrollArea", "ScrollAreaThumb").ScrollAreaThumb
+local ScrollAreaViewport = TS.import(script, script, "ScrollArea", "ScrollAreaViewport").ScrollAreaViewport
+local ScrollArea = {
+	Root = ScrollAreaRoot,
+	Viewport = ScrollAreaViewport,
+	Scrollbar = ScrollAreaScrollbar,
+	Thumb = ScrollAreaThumb,
+	Corner = ScrollAreaCorner,
+}
+local _scrollMath = TS.import(script, script, "ScrollArea", "scrollMath")
+exports.resolveCanvasPositionFromThumbOffset = _scrollMath.resolveCanvasPositionFromThumbOffset
+exports.resolveThumbOffset = _scrollMath.resolveThumbOffset
+exports.resolveThumbSize = _scrollMath.resolveThumbSize
+exports.ScrollArea = ScrollArea
+return exports

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@lattice-ui/scroll-area",
+  "version": "0.3.0",
+  "private": false,
+  "main": "out/init.luau",
+  "types": "out/index.d.ts",
+  "dependencies": {
+    "@lattice-ui/core": "0.3.0"
+  },
+  "devDependencies": {
+    "@rbxts/react": "17.3.7-ts.1",
+    "@rbxts/react-roblox": "17.3.7-ts.1"
+  },
+  "peerDependencies": {
+    "@rbxts/react": "^17",
+    "@rbxts/react-roblox": "^17"
+  },
+  "scripts": {
+    "build": "rbxtsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "watch": "rbxtsc -p tsconfig.json -w"
+  }
+}

package/src/ScrollArea/ScrollAreaCorner.tsx

@@ -0,0 +1,29 @@
+import { React, Slot } from "@lattice-ui/core";
+import { useScrollAreaContext } from "./context";
+import type { ScrollAreaCornerProps } from "./types";
+
+export function ScrollAreaCorner(props: ScrollAreaCornerProps) {
+  const scrollAreaContext = useScrollAreaContext();
+  const visible = scrollAreaContext.showHorizontalScrollbar && scrollAreaContext.showVerticalScrollbar;
+
+  if (props.asChild) {
+    const child = props.children;
+    if (!child) {
+      error("[ScrollAreaCorner] `asChild` requires a child element.");
+    }
+
+    return <Slot Visible={visible}>{child}</Slot>;
+  }
+
+  return (
+    <frame
+      BackgroundColor3={Color3.fromRGB(44, 52, 67)}
+      BorderSizePixel={0}
+      Position={UDim2.fromScale(1, 1)}
+      Size={UDim2.fromOffset(8, 8)}
+      Visible={visible}
+    >
+      {props.children}
+    </frame>
+  );
+}

package/src/ScrollArea/ScrollAreaRoot.tsx

@@ -0,0 +1,99 @@
+import { React } from "@lattice-ui/core";
+import { ScrollAreaContextProvider } from "./context";
+import type { ScrollAreaProps, ScrollAxisMetrics } from "./types";
+
+function createAxisMetrics(): ScrollAxisMetrics {
+  return {
+    viewportSize: 0,
+    contentSize: 0,
+    scrollPosition: 0,
+  };
+}
+
+export function ScrollAreaRoot(props: ScrollAreaProps) {
+  const scrollType = props.type ?? "auto";
+  const scrollHideDelayMs = math.max(0, props.scrollHideDelayMs ?? 600);
+
+  const viewportRef = React.useRef<ScrollingFrame>();
+  const [metrics, setMetrics] = React.useState(() => ({
+    vertical: createAxisMetrics(),
+    horizontal: createAxisMetrics(),
+  }));
+  const [showScrollbarsFromActivity, setShowScrollbarsFromActivity] = React.useState(scrollType !== "scroll");
+  const activitySequenceRef = React.useRef(0);
+
+  React.useEffect(() => {
+    if (scrollType !== "scroll") {
+      setShowScrollbarsFromActivity(true);
+    }
+  }, [scrollType]);
+
+  const setViewport = React.useCallback((instance: ScrollingFrame | undefined) => {
+    viewportRef.current = instance;
+  }, []);
+
+  const notifyScrollActivity = React.useCallback(() => {
+    if (scrollType !== "scroll") {
+      return;
+    }
+
+    activitySequenceRef.current += 1;
+    const sequence = activitySequenceRef.current;
+
+    setShowScrollbarsFromActivity(true);
+
+    task.delay(scrollHideDelayMs / 1000, () => {
+      if (sequence !== activitySequenceRef.current) {
+        return;
+      }
+
+      setShowScrollbarsFromActivity(false);
+    });
+  }, [scrollHideDelayMs, scrollType]);
+
+  const hasVerticalOverflow = metrics.vertical.contentSize > metrics.vertical.viewportSize + 1;
+  const hasHorizontalOverflow = metrics.horizontal.contentSize > metrics.horizontal.viewportSize + 1;
+
+  const showVerticalScrollbar =
+    scrollType === "always"
+      ? hasVerticalOverflow
+      : scrollType === "scroll"
+        ? hasVerticalOverflow && showScrollbarsFromActivity
+        : hasVerticalOverflow;
+
+  const showHorizontalScrollbar =
+    scrollType === "always"
+      ? hasHorizontalOverflow
+      : scrollType === "scroll"
+        ? hasHorizontalOverflow && showScrollbarsFromActivity
+        : hasHorizontalOverflow;
+
+  const contextValue = React.useMemo(
+    () => ({
+      type: scrollType,
+      scrollHideDelayMs,
+      viewportRef,
+      setViewport,
+      vertical: metrics.vertical,
+      horizontal: metrics.horizontal,
+      setMetrics,
+      notifyScrollActivity,
+      showVerticalScrollbar,
+      showHorizontalScrollbar,
+    }),
+    [
+      metrics.horizontal,
+      metrics.vertical,
+      notifyScrollActivity,
+      scrollHideDelayMs,
+      setViewport,
+      showHorizontalScrollbar,
+      showVerticalScrollbar,
+      scrollType,
+    ],
+  );
+
+  return <ScrollAreaContextProvider value={contextValue}>{props.children}</ScrollAreaContextProvider>;
+}
+
+export { ScrollAreaRoot as ScrollArea };

package/src/ScrollArea/ScrollAreaScrollbar.tsx

@@ -0,0 +1,31 @@
+import { React, Slot } from "@lattice-ui/core";
+import { useScrollAreaContext } from "./context";
+import type { ScrollAreaScrollbarProps } from "./types";
+
+export function ScrollAreaScrollbar(props: ScrollAreaScrollbarProps) {
+  const scrollAreaContext = useScrollAreaContext();
+
+  const vertical = props.orientation === "vertical";
+  const visible = vertical ? scrollAreaContext.showVerticalScrollbar : scrollAreaContext.showHorizontalScrollbar;
+
+  if (props.asChild) {
+    const child = props.children;
+    if (!child) {
+      error("[ScrollAreaScrollbar] `asChild` requires a child element.");
+    }
+
+    return <Slot Visible={visible}>{child}</Slot>;
+  }
+
+  return (
+    <frame
+      BackgroundColor3={Color3.fromRGB(44, 52, 67)}
+      BorderSizePixel={0}
+      Position={vertical ? UDim2.fromScale(1, 0) : UDim2.fromScale(0, 1)}
+      Size={vertical ? UDim2.fromOffset(8, 160) : UDim2.fromOffset(260, 8)}
+      Visible={visible}
+    >
+      {props.children}
+    </frame>
+  );
+}

package/src/ScrollArea/ScrollAreaThumb.tsx

@@ -0,0 +1,51 @@
+import { React, Slot } from "@lattice-ui/core";
+import { useScrollAreaContext } from "./context";
+import { resolveThumbOffset, resolveThumbSize } from "./scrollMath";
+import type { ScrollAreaThumbProps } from "./types";
+
+export function ScrollAreaThumb(props: ScrollAreaThumbProps) {
+  const scrollAreaContext = useScrollAreaContext();
+  const vertical = props.orientation === "vertical";
+
+  const axisMetrics = vertical ? scrollAreaContext.vertical : scrollAreaContext.horizontal;
+  const trackSize = math.max(1, axisMetrics.viewportSize);
+  const thumbSize = resolveThumbSize(axisMetrics.viewportSize, axisMetrics.contentSize, trackSize);
+  const thumbOffset = resolveThumbOffset(
+    axisMetrics.scrollPosition,
+    axisMetrics.viewportSize,
+    axisMetrics.contentSize,
+    trackSize,
+    thumbSize,
+  );
+
+  const sizeScale = trackSize > 0 ? thumbSize / trackSize : 1;
+  const offsetScale = trackSize > 0 ? thumbOffset / trackSize : 0;
+
+  if (props.asChild) {
+    const child = props.children;
+    if (!child) {
+      error("[ScrollAreaThumb] `asChild` requires a child element.");
+    }
+
+    return (
+      <Slot
+        Position={vertical ? UDim2.fromScale(0, offsetScale) : UDim2.fromScale(offsetScale, 0)}
+        Size={vertical ? UDim2.fromScale(1, sizeScale) : UDim2.fromScale(sizeScale, 1)}
+      >
+        {child}
+      </Slot>
+    );
+  }
+
+  return (
+    <frame
+      BackgroundColor3={Color3.fromRGB(118, 128, 149)}
+      BorderSizePixel={0}
+      Position={vertical ? UDim2.fromScale(0, offsetScale) : UDim2.fromScale(offsetScale, 0)}
+      Size={vertical ? UDim2.fromScale(1, sizeScale) : UDim2.fromScale(sizeScale, 1)}
+    >
+      <uicorner CornerRadius={new UDim(1, 0)} />
+      {props.children}
+    </frame>
+  );
+}

package/src/ScrollArea/ScrollAreaViewport.tsx

@@ -0,0 +1,86 @@
+import { React, Slot } from "@lattice-ui/core";
+import { useScrollAreaContext } from "./context";
+import type { ScrollAreaViewportProps } from "./types";
+
+function toScrollingFrame(instance: Instance | undefined) {
+  if (!instance || !instance.IsA("ScrollingFrame")) {
+    return undefined;
+  }
+
+  return instance;
+}
+
+export function ScrollAreaViewport(props: ScrollAreaViewportProps) {
+  const scrollAreaContext = useScrollAreaContext();
+
+  const setViewportRef = React.useCallback(
+    (instance: Instance | undefined) => {
+      scrollAreaContext.setViewport(toScrollingFrame(instance));
+    },
+    [scrollAreaContext],
+  );
+
+  React.useEffect(() => {
+    const viewport = scrollAreaContext.viewportRef.current;
+    if (!viewport) {
+      return;
+    }
+
+    const updateMetrics = () => {
+      scrollAreaContext.setMetrics({
+        vertical: {
+          viewportSize: viewport.AbsoluteWindowSize.Y,
+          contentSize: viewport.AbsoluteCanvasSize.Y,
+          scrollPosition: viewport.CanvasPosition.Y,
+        },
+        horizontal: {
+          viewportSize: viewport.AbsoluteWindowSize.X,
+          contentSize: viewport.AbsoluteCanvasSize.X,
+          scrollPosition: viewport.CanvasPosition.X,
+        },
+      });
+    };
+
+    updateMetrics();
+
+    const canvasConnection = viewport.GetPropertyChangedSignal("CanvasPosition").Connect(() => {
+      updateMetrics();
+      scrollAreaContext.notifyScrollActivity();
+    });
+
+    const absoluteCanvasConnection = viewport.GetPropertyChangedSignal("AbsoluteCanvasSize").Connect(updateMetrics);
+    const absoluteWindowConnection = viewport.GetPropertyChangedSignal("AbsoluteWindowSize").Connect(updateMetrics);
+
+    return () => {
+      canvasConnection.Disconnect();
+      absoluteCanvasConnection.Disconnect();
+      absoluteWindowConnection.Disconnect();
+    };
+  }, [scrollAreaContext]);
+
+  if (props.asChild) {
+    const child = props.children;
+    if (!child) {
+      error("[ScrollAreaViewport] `asChild` requires a child element.");
+    }
+
+    return <Slot ref={setViewportRef}>{child}</Slot>;
+  }
+
+  return (
+    <scrollingframe
+      Active
+      AutomaticCanvasSize={Enum.AutomaticSize.XY}
+      BackgroundTransparency={1}
+      BorderSizePixel={0}
+      CanvasSize={UDim2.fromScale(0, 0)}
+      ScrollBarImageTransparency={1}
+      ScrollBarThickness={0}
+      ScrollingDirection={Enum.ScrollingDirection.XY}
+      Size={UDim2.fromOffset(260, 160)}
+      ref={setViewportRef}
+    >
+      {props.children}
+    </scrollingframe>
+  );
+}

package/src/ScrollArea/context.ts

@@ -0,0 +1,6 @@
+import { createStrictContext } from "@lattice-ui/core";
+import type { ScrollAreaContextValue } from "./types";
+
+const [ScrollAreaContextProvider, useScrollAreaContext] = createStrictContext<ScrollAreaContextValue>("ScrollArea");
+
+export { ScrollAreaContextProvider, useScrollAreaContext };

package/src/ScrollArea/scrollMath.ts

@@ -0,0 +1,45 @@
+export function resolveThumbSize(viewportSize: number, contentSize: number, trackSize: number, minimumThumbSize = 18) {
+  if (viewportSize <= 0 || contentSize <= 0 || trackSize <= 0) {
+    return minimumThumbSize;
+  }
+
+  if (contentSize <= viewportSize) {
+    return trackSize;
+  }
+
+  const proportionalSize = (viewportSize / contentSize) * trackSize;
+  return math.clamp(proportionalSize, minimumThumbSize, trackSize);
+}
+
+export function resolveThumbOffset(
+  scrollPosition: number,
+  viewportSize: number,
+  contentSize: number,
+  trackSize: number,
+  thumbSize: number,
+) {
+  if (contentSize <= viewportSize || trackSize <= thumbSize) {
+    return 0;
+  }
+
+  const maxScroll = math.max(1, contentSize - viewportSize);
+  const maxThumbOffset = trackSize - thumbSize;
+  return math.clamp((scrollPosition / maxScroll) * maxThumbOffset, 0, maxThumbOffset);
+}
+
+export function resolveCanvasPositionFromThumbOffset(
+  thumbOffset: number,
+  viewportSize: number,
+  contentSize: number,
+  trackSize: number,
+  thumbSize: number,
+) {
+  if (contentSize <= viewportSize || trackSize <= thumbSize) {
+    return 0;
+  }
+
+  const maxScroll = math.max(1, contentSize - viewportSize);
+  const maxThumbOffset = trackSize - thumbSize;
+  const ratio = math.clamp(thumbOffset / maxThumbOffset, 0, 1);
+  return ratio * maxScroll;
+}

package/src/ScrollArea/types.ts

@@ -0,0 +1,51 @@
+import type React from "@rbxts/react";
+
+export type ScrollAreaType = "auto" | "always" | "scroll";
+export type ScrollAreaOrientation = "vertical" | "horizontal";
+
+export type ScrollAxisMetrics = {
+  viewportSize: number;
+  contentSize: number;
+  scrollPosition: number;
+};
+
+export type ScrollAreaContextValue = {
+  type: ScrollAreaType;
+  scrollHideDelayMs: number;
+  viewportRef: React.MutableRefObject<ScrollingFrame | undefined>;
+  setViewport: (instance: ScrollingFrame | undefined) => void;
+  vertical: ScrollAxisMetrics;
+  horizontal: ScrollAxisMetrics;
+  setMetrics: (metrics: { vertical: ScrollAxisMetrics; horizontal: ScrollAxisMetrics }) => void;
+  notifyScrollActivity: () => void;
+  showVerticalScrollbar: boolean;
+  showHorizontalScrollbar: boolean;
+};
+
+export type ScrollAreaProps = {
+  type?: ScrollAreaType;
+  scrollHideDelayMs?: number;
+  children?: React.ReactNode;
+};
+
+export type ScrollAreaViewportProps = {
+  asChild?: boolean;
+  children?: React.ReactElement;
+};
+
+export type ScrollAreaScrollbarProps = {
+  orientation: ScrollAreaOrientation;
+  asChild?: boolean;
+  children?: React.ReactElement;
+};
+
+export type ScrollAreaThumbProps = {
+  orientation: ScrollAreaOrientation;
+  asChild?: boolean;
+  children?: React.ReactElement;
+};
+
+export type ScrollAreaCornerProps = {
+  asChild?: boolean;
+  children?: React.ReactElement;
+};

package/src/index.ts

@@ -0,0 +1,26 @@
+import { ScrollAreaCorner } from "./ScrollArea/ScrollAreaCorner";
+import { ScrollAreaRoot } from "./ScrollArea/ScrollAreaRoot";
+import { ScrollAreaScrollbar } from "./ScrollArea/ScrollAreaScrollbar";
+import { ScrollAreaThumb } from "./ScrollArea/ScrollAreaThumb";
+import { ScrollAreaViewport } from "./ScrollArea/ScrollAreaViewport";
+
+export const ScrollArea = {
+  Root: ScrollAreaRoot,
+  Viewport: ScrollAreaViewport,
+  Scrollbar: ScrollAreaScrollbar,
+  Thumb: ScrollAreaThumb,
+  Corner: ScrollAreaCorner,
+} as const;
+
+export { resolveCanvasPositionFromThumbOffset, resolveThumbOffset, resolveThumbSize } from "./ScrollArea/scrollMath";
+export type {
+  ScrollAreaContextValue,
+  ScrollAreaCornerProps,
+  ScrollAreaOrientation,
+  ScrollAreaProps,
+  ScrollAreaScrollbarProps,
+  ScrollAreaThumbProps,
+  ScrollAreaType,
+  ScrollAreaViewportProps,
+  ScrollAxisMetrics,
+} from "./ScrollArea/types";

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "out",
+    "declaration": true,
+    "typeRoots": [
+      "./node_modules/@rbxts",
+      "../../node_modules/@rbxts",
+      "./node_modules/@lattice-ui",
+      "../../node_modules/@lattice-ui"
+    ],
+    "types": ["types", "compiler-types"]
+  },
+  "include": ["src"]
+}

package/tsconfig.typecheck.json

@@ -0,0 +1,35 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "baseUrl": "..",
+    "rootDir": "..",
+    "paths": {
+      "@lattice-ui/accordion": ["accordion/src/index.ts"],
+      "@lattice-ui/avatar": ["avatar/src/index.ts"],
+      "@lattice-ui/checkbox": ["checkbox/src/index.ts"],
+      "@lattice-ui/combobox": ["combobox/src/index.ts"],
+      "@lattice-ui/core": ["core/src/index.ts"],
+      "@lattice-ui/dialog": ["dialog/src/index.ts"],
+      "@lattice-ui/focus": ["focus/src/index.ts"],
+      "@lattice-ui/layer": ["layer/src/index.ts"],
+      "@lattice-ui/menu": ["menu/src/index.ts"],
+      "@lattice-ui/popover": ["popover/src/index.ts"],
+      "@lattice-ui/popper": ["popper/src/index.ts"],
+      "@lattice-ui/progress": ["progress/src/index.ts"],
+      "@lattice-ui/radio-group": ["radio-group/src/index.ts"],
+      "@lattice-ui/scroll-area": ["scroll-area/src/index.ts"],
+      "@lattice-ui/select": ["select/src/index.ts"],
+      "@lattice-ui/slider": ["slider/src/index.ts"],
+      "@lattice-ui/style": ["style/src/index.ts"],
+      "@lattice-ui/switch": ["switch/src/index.ts"],
+      "@lattice-ui/system": ["system/src/index.ts"],
+      "@lattice-ui/tabs": ["tabs/src/index.ts"],
+      "@lattice-ui/text-field": ["text-field/src/index.ts"],
+      "@lattice-ui/textarea": ["textarea/src/index.ts"],
+      "@lattice-ui/toast": ["toast/src/index.ts"],
+      "@lattice-ui/toggle-group": ["toggle-group/src/index.ts"],
+      "@lattice-ui/tooltip": ["tooltip/src/index.ts"]
+    }
+  }
+}