@lattice-ui/focus 0.1.1

package/README.md

@@ -0,0 +1,15 @@
+# @lattice-ui/focus
+
+This package is intentionally a skeleton in the current phase.
+
+## Current status
+
+- `FocusScope` and `RovingFocusGroup` are no-op placeholders.
+- Public API is kept stable while layer/popper hardening lands first.
+
+## Next implementation targets
+
+- `FocusScope`: trap + restore behavior for dialog-like surfaces.
+- `RovingFocusGroup`: keyboard/gamepad directional navigation.
+- `GuiService.SelectedObject` + `NextSelection*` graph management.
+- Focus restore flow to trigger elements when scope closes.

package/out/FocusScope/FocusScope.d.ts

@@ -0,0 +1,3 @@
+import type React from "@rbxts/react";
+import type { FocusScopeProps } from "./types";
+export declare function FocusScope(props: FocusScopeProps): React.ReactNode;

package/out/FocusScope/FocusScope.luau

@@ -0,0 +1,7 @@
+-- Compiled with roblox-ts v3.0.0
+local function FocusScope(props)
+	return props.children
+end
+return {
+	FocusScope = FocusScope,
+}

package/out/FocusScope/focusManager.d.ts

@@ -0,0 +1,4 @@
+export declare const GuiService: GuiService;
+export type FocusSnapshot = GuiObject | undefined;
+export declare function captureFocus(): FocusSnapshot;
+export declare function restoreFocus(snapshot: FocusSnapshot): void;

package/out/FocusScope/focusManager.luau

@@ -0,0 +1,13 @@
+-- Compiled with roblox-ts v3.0.0
+local GuiService = game:GetService("GuiService")
+local function captureFocus()
+	return GuiService.SelectedObject
+end
+local function restoreFocus(snapshot)
+	GuiService.SelectedObject = snapshot
+end
+return {
+	captureFocus = captureFocus,
+	restoreFocus = restoreFocus,
+	GuiService = GuiService,
+}

package/out/FocusScope/types.d.ts

@@ -0,0 +1,6 @@
+import type React from "@rbxts/react";
+export type FocusScopeProps = {
+    trapped?: boolean;
+    restoreFocus?: boolean;
+    children?: React.ReactNode;
+};

package/out/FocusScope/types.luau

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

package/out/RovingFocus/RovingFocusGroup.d.ts

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

package/out/RovingFocus/RovingFocusGroup.luau

@@ -0,0 +1,196 @@
+-- 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 _guiSelection = TS.import(script, script.Parent.Parent, "internals", "guiSelection")
+local getSelectedGuiObject = _guiSelection.getSelectedGuiObject
+local setSelectedGuiObject = _guiSelection.setSelectedGuiObject
+local UserInputService = _guiSelection.UserInputService
+local RovingFocusProvider = TS.import(script, script.Parent, "context").RovingFocusProvider
+local _roving = TS.import(script, script.Parent, "roving")
+local getFirstEnabledRovingIndex = _roving.getFirstEnabledRovingIndex
+local getLastEnabledRovingIndex = _roving.getLastEnabledRovingIndex
+local getNextRovingIndex = _roving.getNextRovingIndex
+local function findCurrentIndex(items, selectedObject)
+	if not selectedObject then
+		return -1
+	end
+	-- ▼ ReadonlyArray.findIndex ▼
+	local _callback = function(item)
+		local node = item.getNode()
+		if not node then
+			return false
+		end
+		return selectedObject == node or selectedObject:IsDescendantOf(node)
+	end
+	local _result = -1
+	for _i, _v in items do
+		if _callback(_v, _i - 1, items) == true then
+			_result = _i - 1
+			break
+		end
+	end
+	-- ▲ ReadonlyArray.findIndex ▲
+	return _result
+end
+local function isItemDisabled(items, index)
+	local item = items[index + 1]
+	if not item then
+		return true
+	end
+	return item.getDisabled()
+end
+local function focusItem(items, index)
+	local item = items[index + 1]
+	if not item then
+		return nil
+	end
+	if item.getDisabled() then
+		return nil
+	end
+	local node = item.getNode()
+	if not node or not node.Selectable then
+		return nil
+	end
+	setSelectedGuiObject(node)
+end
+local function resolveArrowDirection(keyCode, orientation)
+	if (orientation == "vertical" or orientation == "both") and keyCode == Enum.KeyCode.Up then
+		return "prev"
+	end
+	if (orientation == "vertical" or orientation == "both") and keyCode == Enum.KeyCode.Down then
+		return "next"
+	end
+	if (orientation == "horizontal" or orientation == "both") and keyCode == Enum.KeyCode.Left then
+		return "prev"
+	end
+	if (orientation == "horizontal" or orientation == "both") and keyCode == Enum.KeyCode.Right then
+		return "next"
+	end
+	return nil
+end
+local function RovingFocusGroup(props)
+	local _condition = props.loop
+	if _condition == nil then
+		_condition = true
+	end
+	local loop = _condition
+	local orientation = props.orientation or "both"
+	local _condition_1 = props.active
+	if _condition_1 == nil then
+		_condition_1 = true
+	end
+	local active = _condition_1
+	local autoFocus = props.autoFocus or "none"
+	local itemEntriesRef = React.useRef({})
+	local revision, setRevision = React.useState(0)
+	local registerItem = React.useCallback(function(item)
+		local _current = itemEntriesRef.current
+		local _item = item
+		table.insert(_current, _item)
+		setRevision(function(value)
+			return value + 1
+		end)
+		return function()
+			local _exp = itemEntriesRef.current
+			-- ▼ ReadonlyArray.findIndex ▼
+			local _callback = function(entry)
+				return entry.id == item.id
+			end
+			local _result = -1
+			for _i, _v in _exp do
+				if _callback(_v, _i - 1, _exp) == true then
+					_result = _i - 1
+					break
+				end
+			end
+			-- ▲ ReadonlyArray.findIndex ▲
+			local index = _result
+			if index >= 0 then
+				table.remove(itemEntriesRef.current, index + 1)
+				setRevision(function(value)
+					return value + 1
+				end)
+			end
+		end
+	end, {})
+	React.useEffect(function()
+		if not active or autoFocus ~= "first" then
+			return nil
+		end
+		local items = itemEntriesRef.current
+		local firstEnabledIndex = getFirstEnabledRovingIndex(#items, function(index)
+			return isItemDisabled(items, index)
+		end)
+		if firstEnabledIndex >= 0 then
+			focusItem(items, firstEnabledIndex)
+		end
+	end, { active, autoFocus, revision })
+	React.useEffect(function()
+		if not active then
+			return nil
+		end
+		local connection = UserInputService.InputBegan:Connect(function(inputObject, gameProcessedEvent)
+			if gameProcessedEvent then
+				return nil
+			end
+			local keyCode = inputObject.KeyCode
+			local isHomeKey = keyCode == Enum.KeyCode.Home
+			local isEndKey = keyCode == Enum.KeyCode.End
+			local direction = resolveArrowDirection(keyCode, orientation)
+			if not isHomeKey and not isEndKey and not direction then
+				return nil
+			end
+			local items = itemEntriesRef.current
+			local itemCount = #items
+			if itemCount <= 0 then
+				return nil
+			end
+			local selectedObject = getSelectedGuiObject()
+			local currentIndex = findCurrentIndex(items, selectedObject)
+			if currentIndex < 0 then
+				return nil
+			end
+			if isHomeKey then
+				local firstEnabledIndex = getFirstEnabledRovingIndex(itemCount, function(index)
+					return isItemDisabled(items, index)
+				end)
+				if firstEnabledIndex >= 0 then
+					focusItem(items, firstEnabledIndex)
+				end
+				return nil
+			end
+			if isEndKey then
+				local lastEnabledIndex = getLastEnabledRovingIndex(itemCount, function(index)
+					return isItemDisabled(items, index)
+				end)
+				if lastEnabledIndex >= 0 then
+					focusItem(items, lastEnabledIndex)
+				end
+				return nil
+			end
+			if not direction then
+				return nil
+			end
+			local nextIndex = getNextRovingIndex(currentIndex, itemCount, direction, loop, function(index)
+				return isItemDisabled(items, index)
+			end)
+			if nextIndex >= 0 then
+				focusItem(items, nextIndex)
+			end
+		end)
+		return function()
+			connection:Disconnect()
+		end
+	end, { active, loop, orientation })
+	local contextValue = React.useMemo(function()
+		return {
+			registerItem = registerItem,
+		}
+	end, { registerItem })
+	return React.createElement(RovingFocusProvider, {
+		value = contextValue,
+	}, props.children)
+end
+return {
+	RovingFocusGroup = RovingFocusGroup,
+}

package/out/RovingFocus/RovingFocusItem.d.ts

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

package/out/RovingFocus/RovingFocusItem.luau

@@ -0,0 +1,66 @@
+-- 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 useRovingFocusContext = TS.import(script, script.Parent, "context").useRovingFocusContext
+local nextRovingItemId = 0
+local function toGuiObject(instance)
+	if not instance or not instance:IsA("GuiObject") then
+		return nil
+	end
+	return instance
+end
+local function RovingFocusItem(props)
+	local rovingFocusContext = useRovingFocusContext()
+	local itemRef = React.useRef()
+	local disabledRef = React.useRef(props.disabled == true)
+	React.useEffect(function()
+		disabledRef.current = props.disabled == true
+	end, { props.disabled })
+	local itemIdRef = React.useRef(0)
+	if itemIdRef.current == 0 then
+		nextRovingItemId += 1
+		itemIdRef.current = nextRovingItemId
+	end
+	React.useEffect(function()
+		return rovingFocusContext.registerItem({
+			id = itemIdRef.current,
+			getNode = function()
+				return itemRef.current
+			end,
+			getDisabled = function()
+				return disabledRef.current
+			end,
+		})
+	end, { rovingFocusContext })
+	local setItemRef = React.useCallback(function(instance)
+		itemRef.current = toGuiObject(instance)
+	end, {})
+	if props.asChild then
+		local child = props.children
+		if not child then
+			error("[RovingFocusItem] `asChild` requires a child element.")
+		end
+		return React.createElement(Slot, {
+			Active = props.disabled ~= true,
+			Selectable = props.disabled ~= true,
+			ref = setItemRef,
+		}, child)
+	end
+	return React.createElement("textbutton", {
+		Active = props.disabled ~= true,
+		AutoButtonColor = false,
+		BackgroundTransparency = 1,
+		BorderSizePixel = 0,
+		Selectable = props.disabled ~= true,
+		Size = UDim2.fromOffset(140, 30),
+		Text = "Item",
+		TextColor3 = Color3.fromRGB(240, 244, 250),
+		TextSize = 15,
+		ref = setItemRef,
+	}, props.children)
+end
+return {
+	RovingFocusItem = RovingFocusItem,
+}

package/out/RovingFocus/context.d.ts

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

package/out/RovingFocus/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("RovingFocusGroup")
+local RovingFocusProvider = _binding[1]
+local useRovingFocusContext = _binding[2]
+return {
+	RovingFocusProvider = RovingFocusProvider,
+	useRovingFocusContext = useRovingFocusContext,
+}

package/out/RovingFocus/roving.d.ts

@@ -0,0 +1,4 @@
+import type { RovingDirection } from "./types";
+export declare function getNextRovingIndex(currentIndex: number, itemCount: number, direction: RovingDirection, loop: boolean, isDisabled?: (index: number) => boolean): number;
+export declare function getFirstEnabledRovingIndex(itemCount: number, isDisabled?: (index: number) => boolean): number;
+export declare function getLastEnabledRovingIndex(itemCount: number, isDisabled?: (index: number) => boolean): number;

package/out/RovingFocus/roving.luau

@@ -0,0 +1,85 @@
+-- Compiled with roblox-ts v3.0.0
+local function getDirectionDelta(direction)
+	return if direction == "next" then 1 else -1
+end
+local function getNextRovingIndex(currentIndex, itemCount, direction, loop, isDisabled)
+	if itemCount <= 0 then
+		return -1
+	end
+	-- Keep focus unchanged when the current index is outside this group.
+	if currentIndex < 0 or currentIndex >= itemCount then
+		return currentIndex
+	end
+	local delta = getDirectionDelta(direction)
+	local candidate = currentIndex
+	do
+		local attempts = 0
+		local _shouldIncrement = false
+		while true do
+			if _shouldIncrement then
+				attempts += 1
+			else
+				_shouldIncrement = true
+			end
+			if not (attempts < itemCount) then
+				break
+			end
+			candidate += delta
+			if candidate < 0 or candidate >= itemCount then
+				if not loop then
+					return currentIndex
+				end
+				candidate = if direction == "next" then 0 else itemCount - 1
+			end
+			if not isDisabled or not isDisabled(candidate) then
+				return candidate
+			end
+		end
+	end
+	return currentIndex
+end
+local function getFirstEnabledRovingIndex(itemCount, isDisabled)
+	do
+		local index = 0
+		local _shouldIncrement = false
+		while true do
+			if _shouldIncrement then
+				index += 1
+			else
+				_shouldIncrement = true
+			end
+			if not (index < itemCount) then
+				break
+			end
+			if not isDisabled or not isDisabled(index) then
+				return index
+			end
+		end
+	end
+	return -1
+end
+local function getLastEnabledRovingIndex(itemCount, isDisabled)
+	do
+		local index = itemCount - 1
+		local _shouldIncrement = false
+		while true do
+			if _shouldIncrement then
+				index -= 1
+			else
+				_shouldIncrement = true
+			end
+			if not (index >= 0) then
+				break
+			end
+			if not isDisabled or not isDisabled(index) then
+				return index
+			end
+		end
+	end
+	return -1
+end
+return {
+	getNextRovingIndex = getNextRovingIndex,
+	getFirstEnabledRovingIndex = getFirstEnabledRovingIndex,
+	getLastEnabledRovingIndex = getLastEnabledRovingIndex,
+}

package/out/RovingFocus/types.d.ts

@@ -0,0 +1,25 @@
+import type React from "@rbxts/react";
+export type RovingDirection = "next" | "prev";
+export type RovingOrientation = "horizontal" | "vertical" | "both";
+export type RovingAutoFocus = "none" | "first";
+export type RovingFocusGroupProps = {
+    loop?: boolean;
+    orientation?: RovingOrientation;
+    active?: boolean;
+    autoFocus?: RovingAutoFocus;
+    children?: React.ReactNode;
+};
+export type RovingFocusItemProps = {
+    asChild?: boolean;
+    disabled?: boolean;
+    children?: React.ReactElement;
+};
+export type RovingItemRegistration = {
+    id: number;
+    getNode: () => GuiObject | undefined;
+    getDisabled: () => boolean;
+};
+export type RovingFocusContextValue = {
+    registerItem: (item: RovingItemRegistration) => () => void;
+    children?: React.ReactNode;
+};

package/out/RovingFocus/types.luau

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

package/out/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./FocusScope/FocusScope";
+export * from "./RovingFocus/RovingFocusGroup";
+export * from "./RovingFocus/RovingFocusItem";

package/out/init.luau

@@ -0,0 +1,13 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local exports = {}
+for _k, _v in TS.import(script, script, "FocusScope", "FocusScope") or {} do
+	exports[_k] = _v
+end
+for _k, _v in TS.import(script, script, "RovingFocus", "RovingFocusGroup") or {} do
+	exports[_k] = _v
+end
+for _k, _v in TS.import(script, script, "RovingFocus", "RovingFocusItem") or {} do
+	exports[_k] = _v
+end
+return exports

package/out/internals/guiSelection.d.ts

@@ -0,0 +1,3 @@
+export declare const UserInputService: UserInputService;
+export declare function getSelectedGuiObject(): GuiObject | undefined;
+export declare function setSelectedGuiObject(guiObject: GuiObject | undefined): void;

package/out/internals/guiSelection.luau

@@ -0,0 +1,15 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local GuiService = TS.import(script, script.Parent.Parent, "FocusScope", "focusManager").GuiService
+local UserInputService = game:GetService("UserInputService")
+local function getSelectedGuiObject()
+	return GuiService.SelectedObject
+end
+local function setSelectedGuiObject(guiObject)
+	GuiService.SelectedObject = guiObject
+end
+return {
+	getSelectedGuiObject = getSelectedGuiObject,
+	setSelectedGuiObject = setSelectedGuiObject,
+	UserInputService = UserInputService,
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@lattice-ui/focus",
+  "version": "0.1.1",
+  "private": false,
+  "main": "out/init.luau",
+  "types": "out/index.d.ts",
+  "dependencies": {
+    "@lattice-ui/core": "0.1.1"
+  },
+  "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",
+    "watch": "rbxtsc -p tsconfig.json -w",
+    "typecheck": "tsc -p tsconfig.typecheck.json"
+  }
+}

package/src/FocusScope/FocusScope.tsx

@@ -0,0 +1,6 @@
+import type React from "@rbxts/react";
+import type { FocusScopeProps } from "./types";
+
+export function FocusScope(props: FocusScopeProps): React.ReactNode {
+  return props.children;
+}

package/src/FocusScope/focusManager.ts

@@ -0,0 +1,11 @@
+export const GuiService = game.GetService("GuiService");
+
+export type FocusSnapshot = GuiObject | undefined;
+
+export function captureFocus(): FocusSnapshot {
+  return GuiService.SelectedObject;
+}
+
+export function restoreFocus(snapshot: FocusSnapshot) {
+  GuiService.SelectedObject = snapshot;
+}

package/src/FocusScope/types.ts

@@ -0,0 +1,7 @@
+import type React from "@rbxts/react";
+
+export type FocusScopeProps = {
+  trapped?: boolean;
+  restoreFocus?: boolean;
+  children?: React.ReactNode;
+};

package/src/RovingFocus/RovingFocusGroup.tsx

@@ -0,0 +1,174 @@
+import { React } from "@lattice-ui/core";
+import { getSelectedGuiObject, setSelectedGuiObject, UserInputService } from "../internals/guiSelection";
+import { RovingFocusProvider } from "./context";
+import { getFirstEnabledRovingIndex, getLastEnabledRovingIndex, getNextRovingIndex } from "./roving";
+import type { RovingDirection, RovingFocusGroupProps, RovingItemRegistration, RovingOrientation } from "./types";
+
+function findCurrentIndex(items: Array<RovingItemRegistration>, selectedObject: GuiObject | undefined) {
+  if (!selectedObject) {
+    return -1;
+  }
+
+  return items.findIndex((item) => {
+    const node = item.getNode();
+    if (!node) {
+      return false;
+    }
+
+    return selectedObject === node || selectedObject.IsDescendantOf(node);
+  });
+}
+
+function isItemDisabled(items: Array<RovingItemRegistration>, index: number) {
+  const item = items[index];
+  if (!item) {
+    return true;
+  }
+
+  return item.getDisabled();
+}
+
+function focusItem(items: Array<RovingItemRegistration>, index: number) {
+  const item = items[index];
+  if (!item) {
+    return;
+  }
+
+  if (item.getDisabled()) {
+    return;
+  }
+
+  const node = item.getNode();
+  if (!node || !node.Selectable) {
+    return;
+  }
+
+  setSelectedGuiObject(node);
+}
+
+function resolveArrowDirection(keyCode: Enum.KeyCode, orientation: RovingOrientation): RovingDirection | undefined {
+  if ((orientation === "vertical" || orientation === "both") && keyCode === Enum.KeyCode.Up) {
+    return "prev";
+  }
+
+  if ((orientation === "vertical" || orientation === "both") && keyCode === Enum.KeyCode.Down) {
+    return "next";
+  }
+
+  if ((orientation === "horizontal" || orientation === "both") && keyCode === Enum.KeyCode.Left) {
+    return "prev";
+  }
+
+  if ((orientation === "horizontal" || orientation === "both") && keyCode === Enum.KeyCode.Right) {
+    return "next";
+  }
+
+  return undefined;
+}
+
+export function RovingFocusGroup(props: RovingFocusGroupProps) {
+  const loop = props.loop ?? true;
+  const orientation = props.orientation ?? "both";
+  const active = props.active ?? true;
+  const autoFocus = props.autoFocus ?? "none";
+
+  const itemEntriesRef = React.useRef<Array<RovingItemRegistration>>([]);
+  const [revision, setRevision] = React.useState(0);
+
+  const registerItem = React.useCallback((item: RovingItemRegistration) => {
+    itemEntriesRef.current.push(item);
+    setRevision((value) => value + 1);
+
+    return () => {
+      const index = itemEntriesRef.current.findIndex((entry) => entry.id === item.id);
+      if (index >= 0) {
+        itemEntriesRef.current.remove(index);
+        setRevision((value) => value + 1);
+      }
+    };
+  }, []);
+
+  React.useEffect(() => {
+    if (!active || autoFocus !== "first") {
+      return;
+    }
+
+    const items = itemEntriesRef.current;
+    const firstEnabledIndex = getFirstEnabledRovingIndex(items.size(), (index) => isItemDisabled(items, index));
+    if (firstEnabledIndex >= 0) {
+      focusItem(items, firstEnabledIndex);
+    }
+  }, [active, autoFocus, revision]);
+
+  React.useEffect(() => {
+    if (!active) {
+      return;
+    }
+
+    const connection = UserInputService.InputBegan.Connect((inputObject, gameProcessedEvent) => {
+      if (gameProcessedEvent) {
+        return;
+      }
+
+      const keyCode = inputObject.KeyCode;
+      const isHomeKey = keyCode === Enum.KeyCode.Home;
+      const isEndKey = keyCode === Enum.KeyCode.End;
+      const direction = resolveArrowDirection(keyCode, orientation);
+      if (!isHomeKey && !isEndKey && !direction) {
+        return;
+      }
+
+      const items = itemEntriesRef.current;
+      const itemCount = items.size();
+      if (itemCount <= 0) {
+        return;
+      }
+
+      const selectedObject = getSelectedGuiObject();
+      const currentIndex = findCurrentIndex(items, selectedObject);
+      if (currentIndex < 0) {
+        return;
+      }
+
+      if (isHomeKey) {
+        const firstEnabledIndex = getFirstEnabledRovingIndex(itemCount, (index) => isItemDisabled(items, index));
+        if (firstEnabledIndex >= 0) {
+          focusItem(items, firstEnabledIndex);
+        }
+        return;
+      }
+
+      if (isEndKey) {
+        const lastEnabledIndex = getLastEnabledRovingIndex(itemCount, (index) => isItemDisabled(items, index));
+        if (lastEnabledIndex >= 0) {
+          focusItem(items, lastEnabledIndex);
+        }
+        return;
+      }
+
+      if (!direction) {
+        return;
+      }
+
+      const nextIndex = getNextRovingIndex(currentIndex, itemCount, direction, loop, (index) =>
+        isItemDisabled(items, index),
+      );
+      if (nextIndex >= 0) {
+        focusItem(items, nextIndex);
+      }
+    });
+
+    return () => {
+      connection.Disconnect();
+    };
+  }, [active, loop, orientation]);
+
+  const contextValue = React.useMemo(
+    () => ({
+      registerItem,
+    }),
+    [registerItem],
+  );
+
+  return <RovingFocusProvider value={contextValue}>{props.children}</RovingFocusProvider>;
+}

package/src/RovingFocus/RovingFocusItem.tsx

@@ -0,0 +1,71 @@
+import { React, Slot } from "@lattice-ui/core";
+import { useRovingFocusContext } from "./context";
+import type { RovingFocusItemProps } from "./types";
+
+let nextRovingItemId = 0;
+
+function toGuiObject(instance: Instance | undefined) {
+  if (!instance || !instance.IsA("GuiObject")) {
+    return undefined;
+  }
+
+  return instance;
+}
+
+export function RovingFocusItem(props: RovingFocusItemProps) {
+  const rovingFocusContext = useRovingFocusContext();
+  const itemRef = React.useRef<GuiObject>();
+  const disabledRef = React.useRef(props.disabled === true);
+
+  React.useEffect(() => {
+    disabledRef.current = props.disabled === true;
+  }, [props.disabled]);
+
+  const itemIdRef = React.useRef(0);
+  if (itemIdRef.current === 0) {
+    nextRovingItemId += 1;
+    itemIdRef.current = nextRovingItemId;
+  }
+
+  React.useEffect(() => {
+    return rovingFocusContext.registerItem({
+      id: itemIdRef.current,
+      getNode: () => itemRef.current,
+      getDisabled: () => disabledRef.current,
+    });
+  }, [rovingFocusContext]);
+
+  const setItemRef = React.useCallback((instance: Instance | undefined) => {
+    itemRef.current = toGuiObject(instance);
+  }, []);
+
+  if (props.asChild) {
+    const child = props.children;
+    if (!child) {
+      error("[RovingFocusItem] `asChild` requires a child element.");
+    }
+
+    return (
+      <Slot Active={props.disabled !== true} Selectable={props.disabled !== true} ref={setItemRef}>
+        {child}
+      </Slot>
+    );
+  }
+
+  return (
+    <textbutton
+      Active={props.disabled !== true}
+      AutoButtonColor={false}
+      BackgroundTransparency={1}
+      BorderSizePixel={0}
+      Selectable={props.disabled !== true}
+      Size={UDim2.fromOffset(140, 30)}
+      Text="Item"
+      TextColor3={Color3.fromRGB(240, 244, 250)}
+      TextSize={15}
+      ref={setItemRef}
+    >
+      {props.children}
+    </textbutton>
+  );
+}

package/src/RovingFocus/context.ts

@@ -0,0 +1,6 @@
+import { createStrictContext } from "@lattice-ui/core";
+import type { RovingFocusContextValue } from "./types";
+
+const [RovingFocusProvider, useRovingFocusContext] = createStrictContext<RovingFocusContextValue>("RovingFocusGroup");
+
+export { RovingFocusProvider, useRovingFocusContext };

package/src/RovingFocus/roving.ts

@@ -0,0 +1,62 @@
+import type { RovingDirection } from "./types";
+
+function getDirectionDelta(direction: RovingDirection) {
+  return direction === "next" ? 1 : -1;
+}
+
+export function getNextRovingIndex(
+  currentIndex: number,
+  itemCount: number,
+  direction: RovingDirection,
+  loop: boolean,
+  isDisabled?: (index: number) => boolean,
+) {
+  if (itemCount <= 0) {
+    return -1;
+  }
+
+  // Keep focus unchanged when the current index is outside this group.
+  if (currentIndex < 0 || currentIndex >= itemCount) {
+    return currentIndex;
+  }
+
+  const delta = getDirectionDelta(direction);
+  let candidate = currentIndex;
+
+  for (let attempts = 0; attempts < itemCount; attempts++) {
+    candidate += delta;
+
+    if (candidate < 0 || candidate >= itemCount) {
+      if (!loop) {
+        return currentIndex;
+      }
+      candidate = direction === "next" ? 0 : itemCount - 1;
+    }
+
+    if (!isDisabled || !isDisabled(candidate)) {
+      return candidate;
+    }
+  }
+
+  return currentIndex;
+}
+
+export function getFirstEnabledRovingIndex(itemCount: number, isDisabled?: (index: number) => boolean) {
+  for (let index = 0; index < itemCount; index++) {
+    if (!isDisabled || !isDisabled(index)) {
+      return index;
+    }
+  }
+
+  return -1;
+}
+
+export function getLastEnabledRovingIndex(itemCount: number, isDisabled?: (index: number) => boolean) {
+  for (let index = itemCount - 1; index >= 0; index--) {
+    if (!isDisabled || !isDisabled(index)) {
+      return index;
+    }
+  }
+
+  return -1;
+}

package/src/RovingFocus/types.ts

@@ -0,0 +1,30 @@
+import type React from "@rbxts/react";
+
+export type RovingDirection = "next" | "prev";
+export type RovingOrientation = "horizontal" | "vertical" | "both";
+export type RovingAutoFocus = "none" | "first";
+
+export type RovingFocusGroupProps = {
+  loop?: boolean;
+  orientation?: RovingOrientation;
+  active?: boolean;
+  autoFocus?: RovingAutoFocus;
+  children?: React.ReactNode;
+};
+
+export type RovingFocusItemProps = {
+  asChild?: boolean;
+  disabled?: boolean;
+  children?: React.ReactElement;
+};
+
+export type RovingItemRegistration = {
+  id: number;
+  getNode: () => GuiObject | undefined;
+  getDisabled: () => boolean;
+};
+
+export type RovingFocusContextValue = {
+  registerItem: (item: RovingItemRegistration) => () => void;
+  children?: React.ReactNode;
+};

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./FocusScope/FocusScope";
+export * from "./RovingFocus/RovingFocusGroup";
+export * from "./RovingFocus/RovingFocusItem";

package/src/internals/guiSelection.ts

@@ -0,0 +1,11 @@
+import { GuiService } from "../FocusScope/focusManager";
+
+export const UserInputService = game.GetService("UserInputService");
+
+export function getSelectedGuiObject() {
+  return GuiService.SelectedObject;
+}
+
+export function setSelectedGuiObject(guiObject: GuiObject | undefined) {
+  GuiService.SelectedObject = guiObject;
+}

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,25 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "baseUrl": "..",
+    "rootDir": "..",
+    "paths": {
+      "@lattice-ui/checkbox": ["checkbox/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/radio-group": ["radio-group/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/toggle-group": ["toggle-group/src/index.ts"],
+      "@lattice-ui/tooltip": ["tooltip/src/index.ts"]
+    }
+  }
+}