@lattice-ui/core 0.3.1 → 0.4.0

package/out/focus/context.d.ts

@@ -0,0 +1,14 @@
+import type ReactType from "@rbxts/react";
+type FocusScopeProviderProps = {
+    scopeId?: number;
+    children?: ReactType.ReactNode;
+};
+type FocusLayerProviderProps = {
+    layerOrder?: number;
+    children?: ReactType.ReactNode;
+};
+export declare function FocusScopeProvider(props: FocusScopeProviderProps): ReactType.JSX.Element;
+export declare function useFocusScopeId(): number | undefined;
+export declare function FocusLayerProvider(props: FocusLayerProviderProps): ReactType.JSX.Element;
+export declare function useFocusLayerOrder(): number | undefined;
+export {};

package/out/focus/context.luau

@@ -0,0 +1,27 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local React = TS.import(script, script.Parent.Parent, "react").default
+local FocusScopeIdContext = React.createContext(nil)
+local FocusLayerOrderContext = React.createContext(nil)
+local function FocusScopeProvider(props)
+	return React.createElement(FocusScopeIdContext.Provider, {
+		value = props.scopeId,
+	}, props.children)
+end
+local function useFocusScopeId()
+	return React.useContext(FocusScopeIdContext)
+end
+local function FocusLayerProvider(props)
+	return React.createElement(FocusLayerOrderContext.Provider, {
+		value = props.layerOrder,
+	}, props.children)
+end
+local function useFocusLayerOrder()
+	return React.useContext(FocusLayerOrderContext)
+end
+return {
+	FocusScopeProvider = FocusScopeProvider,
+	useFocusScopeId = useFocusScopeId,
+	FocusLayerProvider = FocusLayerProvider,
+	useFocusLayerOrder = useFocusLayerOrder,
+}

package/out/focus/env.d.ts

@@ -0,0 +1 @@
+export declare const GuiService: GuiService;

package/out/focus/env.luau

@@ -0,0 +1,5 @@
+-- Compiled with roblox-ts v3.0.0
+local GuiService = game:GetService("GuiService")
+return {
+	GuiService = GuiService,
+}

package/out/focus/focusManager.d.ts

@@ -0,0 +1,44 @@
+export type FocusRestoreSnapshot = {
+    nodeId?: number;
+};
+export type FocusNodeRecord = {
+    id: number;
+    scopeId?: number;
+    implicit: boolean;
+    order: number;
+    getGuiObject: () => GuiObject | undefined;
+    getDisabled: () => boolean;
+    getVisible: () => boolean | undefined;
+    getSyncToRoblox: () => boolean;
+};
+export type RegisterFocusNodeParams = {
+    scopeId?: number;
+    getGuiObject: () => GuiObject | undefined;
+    getDisabled?: () => boolean;
+    getVisible?: () => boolean | undefined;
+    getSyncToRoblox?: () => boolean;
+};
+export type RegisterFocusScopeParams = {
+    parentScopeId?: number;
+    getRoot: () => GuiObject | undefined;
+    getActive: () => boolean;
+    getTrapped: () => boolean;
+    getRestoreFocus?: () => boolean;
+    getLayerOrder?: () => number | undefined;
+};
+export declare function registerFocusNode(params: RegisterFocusNodeParams): number;
+export declare function createFocusScopeId(): number;
+export declare function unregisterFocusNode(nodeId: number): void;
+export declare function registerFocusScope(scopeId: number, params: RegisterFocusScopeParams): number;
+export declare function syncFocusScope(scopeId: number): void;
+export declare function unregisterFocusScope(scopeId: number): void;
+export declare function retainExternalFocusBridge(): void;
+export declare function releaseExternalFocusBridge(): void;
+export declare function canFocusNode(nodeId: number): boolean;
+export declare function focusNode(nodeId: number): GuiObject | undefined;
+export declare function focusGuiObject(guiObject: GuiObject | undefined): GuiObject | undefined;
+export declare function clearFocus(): void;
+export declare function getFocusedNode(): FocusNodeRecord | undefined;
+export declare function getFocusedGuiObject(): GuiObject | undefined;
+export declare function captureRestoreSnapshot(): FocusRestoreSnapshot;
+export declare function restoreSnapshot(snapshot: FocusRestoreSnapshot | undefined): GuiObject | undefined;

package/out/focus/focusManager.luau

@@ -0,0 +1,727 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local GuiService = TS.import(script, script.Parent, "env").GuiService
+local focusNodes = {}
+local focusScopes = {}
+local nextFocusNodeId = 0
+local nextFocusScopeId = 0
+local nextFocusOrder = 0
+local currentFocusedNodeId
+local externalSelectionConsumerCount = 0
+local selectedObjectConnection
+local bridgeWriteDepth = 0
+local function isLiveGuiObject(guiObject)
+	return guiObject ~= nil and guiObject.Parent ~= nil
+end
+local function isEffectivelyVisible(guiObject)
+	if not isLiveGuiObject(guiObject) or not guiObject.Visible then
+		return false
+	end
+	local ancestor = guiObject.Parent
+	while ancestor ~= nil do
+		if ancestor:IsA("GuiObject") and not ancestor.Visible then
+			return false
+		end
+		if ancestor:IsA("LayerCollector") and not ancestor.Enabled then
+			return false
+		end
+		ancestor = ancestor.Parent
+	end
+	return true
+end
+local function isInsideRoot(scopeRoot, guiObject)
+	if not isLiveGuiObject(scopeRoot) or not isLiveGuiObject(guiObject) then
+		return false
+	end
+	return guiObject == scopeRoot or guiObject:IsDescendantOf(scopeRoot)
+end
+local function isRawGuiObjectFocusable(guiObject)
+	return isLiveGuiObject(guiObject) and isEffectivelyVisible(guiObject) and guiObject.Selectable
+end
+local function findFocusNodeIndex(nodeId)
+	-- ▼ ReadonlyArray.findIndex ▼
+	local _callback = function(entry)
+		return entry.id == nodeId
+	end
+	local _result = -1
+	for _i, _v in focusNodes do
+		if _callback(_v, _i - 1, focusNodes) == true then
+			_result = _i - 1
+			break
+		end
+	end
+	-- ▲ ReadonlyArray.findIndex ▲
+	return _result
+end
+local function findFocusScopeIndex(scopeId)
+	-- ▼ ReadonlyArray.findIndex ▼
+	local _callback = function(entry)
+		return entry.id == scopeId
+	end
+	local _result = -1
+	for _i, _v in focusScopes do
+		if _callback(_v, _i - 1, focusScopes) == true then
+			_result = _i - 1
+			break
+		end
+	end
+	-- ▲ ReadonlyArray.findIndex ▲
+	return _result
+end
+local function getFocusNodeRecord(nodeId)
+	if nodeId == nil then
+		return nil
+	end
+	local nodeIndex = findFocusNodeIndex(nodeId)
+	if nodeIndex < 0 then
+		return nil
+	end
+	return focusNodes[nodeIndex + 1]
+end
+local function getFocusScopeRecord(scopeId)
+	if scopeId == nil then
+		return nil
+	end
+	local scopeIndex = findFocusScopeIndex(scopeId)
+	if scopeIndex < 0 then
+		return nil
+	end
+	return focusScopes[scopeIndex + 1]
+end
+local function getNodeOwningScopeId(record, guiObject)
+	if record.scopeId ~= nil then
+		return record.scopeId
+	end
+	if not isLiveGuiObject(guiObject) then
+		return nil
+	end
+	local bestScopeId
+	local bestLayerOrder = -1
+	local bestScopeOrder = -1
+	for _, scopeRecord in focusScopes do
+		local scopeRoot = scopeRecord.getRoot()
+		if not isInsideRoot(scopeRoot, guiObject) then
+			continue
+		end
+		local _condition = scopeRecord.getLayerOrder()
+		if _condition == nil then
+			_condition = 0
+		end
+		local layerOrder = _condition
+		if layerOrder > bestLayerOrder or (layerOrder == bestLayerOrder and scopeRecord.order > bestScopeOrder) then
+			bestScopeId = scopeRecord.id
+			bestLayerOrder = layerOrder
+			bestScopeOrder = scopeRecord.order
+		end
+	end
+	return bestScopeId
+end
+local function isNodeInsideInactiveScope(record, guiObject)
+	local owningScopeId = getNodeOwningScopeId(record, guiObject)
+	local owningScope = getFocusScopeRecord(owningScopeId)
+	return owningScope ~= nil and not owningScope.getActive()
+end
+local function getTopTrappedScope(excludingScopeId)
+	local bestScope
+	for _, scopeRecord in focusScopes do
+		if scopeRecord.id == excludingScopeId or not scopeRecord.getActive() or not scopeRecord.getTrapped() then
+			continue
+		end
+		local scopeRoot = scopeRecord.getRoot()
+		if not isLiveGuiObject(scopeRoot) then
+			continue
+		end
+		if not bestScope then
+			bestScope = scopeRecord
+			continue
+		end
+		local _condition = bestScope.getLayerOrder()
+		if _condition == nil then
+			_condition = 0
+		end
+		local bestLayerOrder = _condition
+		local _condition_1 = scopeRecord.getLayerOrder()
+		if _condition_1 == nil then
+			_condition_1 = 0
+		end
+		local nextLayerOrder = _condition_1
+		if nextLayerOrder > bestLayerOrder or (nextLayerOrder == bestLayerOrder and scopeRecord.order > bestScope.order) then
+			bestScope = scopeRecord
+		end
+	end
+	return bestScope
+end
+local function getResolvedFocusNode(nodeId, options)
+	local record = getFocusNodeRecord(nodeId)
+	if not record then
+		return nil
+	end
+	local guiObject = record.getGuiObject()
+	if not isLiveGuiObject(guiObject) then
+		return nil
+	end
+	if record.getDisabled() then
+		return nil
+	end
+	local explicitVisible = record.getVisible()
+	if explicitVisible == false or not isEffectivelyVisible(guiObject) then
+		return nil
+	end
+	if isNodeInsideInactiveScope(record, guiObject) then
+		return nil
+	end
+	local _result = options
+	if _result ~= nil then
+		_result = _result.trapScopeOverride
+	end
+	local _condition = _result
+	if _condition == nil then
+		_condition = getTopTrappedScope()
+	end
+	local trappedScope = _condition
+	if trappedScope and not isInsideRoot(trappedScope.getRoot(), guiObject) then
+		return nil
+	end
+	return {
+		record = record,
+		guiObject = guiObject,
+	}
+end
+local function canSyncNodeToRoblox(resolvedNode)
+	return resolvedNode.record.getSyncToRoblox() and resolvedNode.guiObject.Selectable
+end
+local function withBridgeWrite(callback)
+	bridgeWriteDepth += 1
+	local result = callback()
+	bridgeWriteDepth -= 1
+	return result
+end
+local function syncRobloxSelection()
+	local resolvedFocusedNode = if currentFocusedNodeId ~= nil then getResolvedFocusNode(currentFocusedNodeId) else nil
+	local nextSelectedObject = if resolvedFocusedNode and canSyncNodeToRoblox(resolvedFocusedNode) then resolvedFocusedNode.guiObject else nil
+	if GuiService.SelectedObject == nextSelectedObject then
+		return nil
+	end
+	withBridgeWrite(function()
+		GuiService.SelectedObject = nextSelectedObject
+	end)
+end
+local function updateScopeLastFocusedNode(nodeId, guiObject)
+	for _, scopeRecord in focusScopes do
+		if not scopeRecord.getActive() then
+			continue
+		end
+		if isInsideRoot(scopeRecord.getRoot(), guiObject) then
+			scopeRecord.lastFocusedNodeId = nodeId
+		end
+	end
+end
+local function setCurrentFocusedNode(nodeId)
+	currentFocusedNodeId = nodeId
+	local resolvedNode = if nodeId ~= nil then getResolvedFocusNode(nodeId) else nil
+	if resolvedNode then
+		updateScopeLastFocusedNode(resolvedNode.record.id, resolvedNode.guiObject)
+	end
+	syncRobloxSelection()
+	local _result = resolvedNode
+	if _result ~= nil then
+		_result = _result.guiObject
+	end
+	return _result
+end
+local function findExistingFocusNodeByGuiObject(guiObject)
+	if not isLiveGuiObject(guiObject) then
+		return nil
+	end
+	for index = #focusNodes - 1, 0, -1 do
+		local nodeRecord = focusNodes[index + 1]
+		if nodeRecord.getGuiObject() == guiObject then
+			return nodeRecord
+		end
+	end
+	return nil
+end
+local function registerImplicitFocusNode(guiObject)
+	local existingNode = findExistingFocusNodeByGuiObject(guiObject)
+	if existingNode then
+		return existingNode
+	end
+	nextFocusNodeId += 1
+	nextFocusOrder += 1
+	local nodeRecord = {
+		id = nextFocusNodeId,
+		scopeId = nil,
+		implicit = true,
+		order = nextFocusOrder,
+		getGuiObject = function()
+			return guiObject
+		end,
+		getDisabled = function()
+			return false
+		end,
+		getVisible = function()
+			return nil
+		end,
+		getSyncToRoblox = function()
+			return true
+		end,
+	}
+	table.insert(focusNodes, nodeRecord)
+	return nodeRecord
+end
+local function resolveFocusNodeByGuiObject(guiObject, options)
+	if not isLiveGuiObject(guiObject) then
+		return nil
+	end
+	local existingNode = findExistingFocusNodeByGuiObject(guiObject)
+	if existingNode then
+		return getResolvedFocusNode(existingNode.id, options)
+	end
+	local _result = options
+	if _result ~= nil then
+		_result = _result.allowImplicit
+	end
+	local _condition = not _result
+	if not _condition then
+		_condition = not isRawGuiObjectFocusable(guiObject)
+	end
+	if _condition then
+		return nil
+	end
+	local implicitNode = registerImplicitFocusNode(guiObject)
+	return getResolvedFocusNode(implicitNode.id, options)
+end
+local function findFirstRegisteredNodeInScope(scopeRecord)
+	for _, nodeRecord in focusNodes do
+		local guiObject = nodeRecord.getGuiObject()
+		if not isInsideRoot(scopeRecord.getRoot(), guiObject) then
+			continue
+		end
+		local resolvedNode = getResolvedFocusNode(nodeRecord.id, {
+			trapScopeOverride = scopeRecord,
+		})
+		if resolvedNode then
+			return resolvedNode
+		end
+	end
+	return nil
+end
+local function findFirstFocusableDescendantInScope(scopeRecord)
+	local scopeRoot = scopeRecord.getRoot()
+	if not isLiveGuiObject(scopeRoot) then
+		return nil
+	end
+	local rootNode = resolveFocusNodeByGuiObject(scopeRoot, {
+		allowImplicit = true,
+		trapScopeOverride = scopeRecord,
+	})
+	if rootNode then
+		return rootNode
+	end
+	for _, descendant in scopeRoot:GetDescendants() do
+		if not descendant:IsA("GuiObject") then
+			continue
+		end
+		local resolvedNode = resolveFocusNodeByGuiObject(descendant, {
+			allowImplicit = true,
+			trapScopeOverride = scopeRecord,
+		})
+		if resolvedNode then
+			return resolvedNode
+		end
+	end
+	return nil
+end
+local function getBestScopeFallbackNode(scopeRecord)
+	local lastFocusedNodeId = scopeRecord.lastFocusedNodeId
+	if lastFocusedNodeId ~= nil then
+		local lastFocusedNode = getResolvedFocusNode(lastFocusedNodeId, {
+			trapScopeOverride = scopeRecord,
+		})
+		if lastFocusedNode and isInsideRoot(scopeRecord.getRoot(), lastFocusedNode.guiObject) then
+			return lastFocusedNode
+		end
+	end
+	return findFirstRegisteredNodeInScope(scopeRecord) or findFirstFocusableDescendantInScope(scopeRecord)
+end
+local function enforceTrappedFocus(excludingScopeId)
+	local trappedScope = getTopTrappedScope(excludingScopeId)
+	if not trappedScope then
+		syncRobloxSelection()
+		return nil
+	end
+	local currentFocusedNode = if currentFocusedNodeId ~= nil then getResolvedFocusNode(currentFocusedNodeId, {
+		trapScopeOverride = trappedScope,
+	}) else nil
+	if currentFocusedNode then
+		syncRobloxSelection()
+		return nil
+	end
+	local fallbackNode = getBestScopeFallbackNode(trappedScope)
+	if fallbackNode then
+		setCurrentFocusedNode(fallbackNode.record.id)
+		return nil
+	end
+	setCurrentFocusedNode(nil)
+end
+local function isFocusNodeReferenced(nodeId)
+	if currentFocusedNodeId == nodeId then
+		return true
+	end
+	for _, scopeRecord in focusScopes do
+		local _condition = scopeRecord.lastFocusedNodeId == nodeId
+		if not _condition then
+			local _result = scopeRecord.restoreSnapshot
+			if _result ~= nil then
+				_result = _result.nodeId
+			end
+			_condition = _result == nodeId
+		end
+		if _condition then
+			return true
+		end
+	end
+	return false
+end
+local function pruneImplicitFocusNodes()
+	for index = #focusNodes - 1, 0, -1 do
+		local nodeRecord = focusNodes[index + 1]
+		if not nodeRecord.implicit then
+			continue
+		end
+		if isLiveGuiObject(nodeRecord.getGuiObject()) or isFocusNodeReferenced(nodeRecord.id) then
+			continue
+		end
+		local _index = index
+		table.remove(focusNodes, _index + 1)
+	end
+end
+local function findBridgeRestoreNode()
+	local selectedObject = GuiService.SelectedObject
+	return resolveFocusNodeByGuiObject(selectedObject, {
+		allowImplicit = true,
+	})
+end
+local getFocusedNode
+local function getCurrentFocusGuiObject()
+	local focusedNode = getFocusedNode()
+	local _result = focusedNode
+	if _result ~= nil then
+		_result = _result.getGuiObject()
+	end
+	local _condition = _result
+	if _condition == nil then
+		_condition = GuiService.SelectedObject
+	end
+	return _condition
+end
+local focusNode, focusGuiObject
+local function restoreScopeFocus(scopeRecord)
+	local _snapshotNodeId = scopeRecord.restoreSnapshot
+	if _snapshotNodeId ~= nil then
+		_snapshotNodeId = _snapshotNodeId.nodeId
+	end
+	local snapshotNodeId = _snapshotNodeId
+	local restoreGuiObject = scopeRecord.restoreGuiObject
+	scopeRecord.restoreSnapshot = nil
+	scopeRecord.restoreGuiObject = nil
+	if snapshotNodeId ~= nil then
+		local restoredGuiObject = focusNode(snapshotNodeId)
+		if restoredGuiObject then
+			return restoredGuiObject
+		end
+	end
+	if restoreGuiObject then
+		local restoredGuiObject = focusGuiObject(restoreGuiObject)
+		if restoredGuiObject then
+			return restoredGuiObject
+		end
+	end
+	local ancestorScope = getFocusScopeRecord(scopeRecord.parentScopeId)
+	while ancestorScope do
+		local fallbackNode = getBestScopeFallbackNode(ancestorScope)
+		if fallbackNode then
+			local restoredGuiObject = focusNode(fallbackNode.record.id)
+			if restoredGuiObject then
+				return restoredGuiObject
+			end
+		end
+		ancestorScope = getFocusScopeRecord(ancestorScope.parentScopeId)
+	end
+	local topTrappedScope = getTopTrappedScope(scopeRecord.id)
+	if topTrappedScope then
+		local fallbackNode = getBestScopeFallbackNode(topTrappedScope)
+		if fallbackNode then
+			local restoredGuiObject = focusNode(fallbackNode.record.id)
+			if restoredGuiObject then
+				return restoredGuiObject
+			end
+		end
+	end
+	setCurrentFocusedNode(nil)
+	return nil
+end
+local function handleExternalSelectedObjectChange()
+	if bridgeWriteDepth > 0 then
+		return nil
+	end
+	local selectedObject = GuiService.SelectedObject
+	local resolvedNode = resolveFocusNodeByGuiObject(selectedObject, {
+		allowImplicit = true,
+	})
+	if resolvedNode then
+		setCurrentFocusedNode(resolvedNode.record.id)
+		return nil
+	end
+	enforceTrappedFocus()
+end
+local function startExternalSelectionListener()
+	if selectedObjectConnection then
+		return nil
+	end
+	selectedObjectConnection = GuiService:GetPropertyChangedSignal("SelectedObject"):Connect(function()
+		handleExternalSelectedObjectChange()
+	end)
+end
+local function stopExternalSelectionListener()
+	if not selectedObjectConnection then
+		return nil
+	end
+	selectedObjectConnection:Disconnect()
+	selectedObjectConnection = nil
+end
+local function syncExternalSelectionListener()
+	if externalSelectionConsumerCount > 0 then
+		startExternalSelectionListener()
+	else
+		stopExternalSelectionListener()
+	end
+end
+local function registerFocusNode(params)
+	nextFocusNodeId += 1
+	nextFocusOrder += 1
+	local nodeRecord = {
+		id = nextFocusNodeId,
+		scopeId = params.scopeId,
+		implicit = false,
+		order = nextFocusOrder,
+		getGuiObject = params.getGuiObject,
+		getDisabled = params.getDisabled or (function()
+			return false
+		end),
+		getVisible = params.getVisible or (function()
+			return nil
+		end),
+		getSyncToRoblox = params.getSyncToRoblox or (function()
+			return true
+		end),
+	}
+	table.insert(focusNodes, nodeRecord)
+	local guiObject = nodeRecord.getGuiObject()
+	local currentFocusedNode = if currentFocusedNodeId ~= nil then getFocusNodeRecord(currentFocusedNodeId) else nil
+	local _result = currentFocusedNode
+	if _result ~= nil then
+		_result = _result.implicit
+	end
+	local _condition = _result
+	if _condition then
+		_condition = currentFocusedNode.getGuiObject() == guiObject
+	end
+	if _condition then
+		currentFocusedNodeId = nodeRecord.id
+		for _, scopeRecord in focusScopes do
+			if scopeRecord.lastFocusedNodeId == currentFocusedNode.id then
+				scopeRecord.lastFocusedNodeId = nodeRecord.id
+			end
+		end
+	end
+	enforceTrappedFocus()
+	return nodeRecord.id
+end
+local function createFocusScopeId()
+	nextFocusScopeId += 1
+	return nextFocusScopeId
+end
+local function unregisterFocusNode(nodeId)
+	local nodeIndex = findFocusNodeIndex(nodeId)
+	if nodeIndex < 0 then
+		return nil
+	end
+	table.remove(focusNodes, nodeIndex + 1)
+	for _, scopeRecord in focusScopes do
+		if scopeRecord.lastFocusedNodeId == nodeId then
+			scopeRecord.lastFocusedNodeId = nil
+		end
+	end
+	if currentFocusedNodeId == nodeId then
+		currentFocusedNodeId = nil
+	end
+	pruneImplicitFocusNodes()
+	enforceTrappedFocus()
+end
+local syncFocusScope
+local function registerFocusScope(scopeId, params)
+	nextFocusOrder += 1
+	local scopeRecord = {
+		id = scopeId,
+		parentScopeId = params.parentScopeId,
+		order = nextFocusOrder,
+		wasActive = false,
+		getRoot = params.getRoot,
+		getActive = params.getActive,
+		getTrapped = params.getTrapped,
+		getRestoreFocus = params.getRestoreFocus or (function()
+			return true
+		end),
+		getLayerOrder = params.getLayerOrder or (function()
+			return nil
+		end),
+	}
+	table.insert(focusScopes, scopeRecord)
+	syncFocusScope(scopeRecord.id)
+	return scopeRecord.id
+end
+local captureRestoreSnapshot
+function syncFocusScope(scopeId)
+	local scopeRecord = getFocusScopeRecord(scopeId)
+	if not scopeRecord then
+		return nil
+	end
+	local nextActive = scopeRecord.getActive()
+	if nextActive and not scopeRecord.wasActive then
+		scopeRecord.restoreSnapshot = if scopeRecord.getRestoreFocus() then captureRestoreSnapshot() else nil
+		scopeRecord.restoreGuiObject = if scopeRecord.getRestoreFocus() then getCurrentFocusGuiObject() else nil
+		scopeRecord.wasActive = true
+		if scopeRecord.getTrapped() then
+			enforceTrappedFocus()
+		end
+	elseif not nextActive and scopeRecord.wasActive then
+		scopeRecord.wasActive = false
+		local scopeIndex = findFocusScopeIndex(scopeId)
+		if scopeIndex >= 0 then
+			table.remove(focusScopes, scopeIndex + 1)
+		end
+		if scopeRecord.getRestoreFocus() then
+			restoreScopeFocus(scopeRecord)
+		else
+			scopeRecord.restoreSnapshot = nil
+			scopeRecord.restoreGuiObject = nil
+			enforceTrappedFocus(scopeRecord.id)
+		end
+		table.insert(focusScopes, scopeRecord)
+	elseif nextActive and scopeRecord.getTrapped() then
+		enforceTrappedFocus()
+	end
+	pruneImplicitFocusNodes()
+end
+local function unregisterFocusScope(scopeId)
+	local scopeIndex = findFocusScopeIndex(scopeId)
+	if scopeIndex < 0 then
+		return nil
+	end
+	local scopeRecord = focusScopes[scopeIndex + 1]
+	table.remove(focusScopes, scopeIndex + 1)
+	if scopeRecord.wasActive and scopeRecord.getRestoreFocus() then
+		restoreScopeFocus(scopeRecord)
+	else
+		enforceTrappedFocus(scopeId)
+	end
+	pruneImplicitFocusNodes()
+end
+local function retainExternalFocusBridge()
+	externalSelectionConsumerCount += 1
+	syncExternalSelectionListener()
+end
+local function releaseExternalFocusBridge()
+	externalSelectionConsumerCount = math.max(0, externalSelectionConsumerCount - 1)
+	syncExternalSelectionListener()
+end
+local function canFocusNode(nodeId)
+	return getResolvedFocusNode(nodeId) ~= nil
+end
+function focusNode(nodeId)
+	local resolvedNode = getResolvedFocusNode(nodeId)
+	if not resolvedNode then
+		return nil
+	end
+	return setCurrentFocusedNode(resolvedNode.record.id)
+end
+function focusGuiObject(guiObject)
+	local resolvedNode = resolveFocusNodeByGuiObject(guiObject, {
+		allowImplicit = true,
+	})
+	if not resolvedNode then
+		return nil
+	end
+	return setCurrentFocusedNode(resolvedNode.record.id)
+end
+local function clearFocus()
+	setCurrentFocusedNode(nil)
+	enforceTrappedFocus()
+end
+function getFocusedNode()
+	if currentFocusedNodeId == nil then
+		return nil
+	end
+	local resolvedNode = getResolvedFocusNode(currentFocusedNodeId)
+	local _result = resolvedNode
+	if _result ~= nil then
+		_result = _result.record
+	end
+	return _result
+end
+local function getFocusedGuiObject()
+	local focusedNode = getFocusedNode()
+	local _result = focusedNode
+	if _result ~= nil then
+		_result = _result.getGuiObject()
+	end
+	return _result
+end
+function captureRestoreSnapshot()
+	local focusedNode = getFocusedNode()
+	if focusedNode then
+		return {
+			nodeId = focusedNode.id,
+		}
+	end
+	local bridgeNode = findBridgeRestoreNode()
+	local _object = {}
+	local _left = "nodeId"
+	local _result = bridgeNode
+	if _result ~= nil then
+		_result = _result.record.id
+	end
+	_object[_left] = _result
+	return _object
+end
+local function restoreSnapshot(snapshot)
+	local _snapshotNodeId = snapshot
+	if _snapshotNodeId ~= nil then
+		_snapshotNodeId = _snapshotNodeId.nodeId
+	end
+	local snapshotNodeId = _snapshotNodeId
+	if snapshotNodeId == nil then
+		clearFocus()
+		return nil
+	end
+	return focusNode(snapshotNodeId)
+end
+return {
+	registerFocusNode = registerFocusNode,
+	createFocusScopeId = createFocusScopeId,
+	unregisterFocusNode = unregisterFocusNode,
+	registerFocusScope = registerFocusScope,
+	syncFocusScope = syncFocusScope,
+	unregisterFocusScope = unregisterFocusScope,
+	retainExternalFocusBridge = retainExternalFocusBridge,
+	releaseExternalFocusBridge = releaseExternalFocusBridge,
+	canFocusNode = canFocusNode,
+	focusNode = focusNode,
+	focusGuiObject = focusGuiObject,
+	clearFocus = clearFocus,
+	getFocusedNode = getFocusedNode,
+	getFocusedGuiObject = getFocusedGuiObject,
+	captureRestoreSnapshot = captureRestoreSnapshot,
+	restoreSnapshot = restoreSnapshot,
+}

package/out/focus/useFocusNode.d.ts

@@ -0,0 +1,10 @@
+import React from "../react";
+export type UseFocusNodeOptions = {
+    ref: React.MutableRefObject<GuiObject | undefined>;
+    scopeId?: number;
+    disabled?: boolean;
+    getDisabled?: () => boolean;
+    getVisible?: () => boolean | undefined;
+    syncToRoblox?: boolean;
+};
+export declare function useFocusNode(options: UseFocusNodeOptions): React.MutableRefObject<number | undefined>;

package/out/focus/useFocusNode.luau

@@ -0,0 +1,65 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local React = TS.import(script, script.Parent.Parent, "react").default
+local useFocusScopeId = TS.import(script, script.Parent, "context").useFocusScopeId
+local _focusManager = TS.import(script, script.Parent, "focusManager")
+local registerFocusNode = _focusManager.registerFocusNode
+local unregisterFocusNode = _focusManager.unregisterFocusNode
+local function useLatest(value)
+	local ref = React.useRef(value)
+	React.useEffect(function()
+		ref.current = value
+	end, { value })
+	return ref
+end
+local function useFocusNode(options)
+	local inheritedScopeId = useFocusScopeId()
+	local _condition = options.scopeId
+	if _condition == nil then
+		_condition = inheritedScopeId
+	end
+	local scopeId = _condition
+	local nodeIdRef = React.useRef()
+	local disabledRef = useLatest(options.disabled == true)
+	local getDisabledRef = useLatest(options.getDisabled)
+	local getVisibleRef = useLatest(options.getVisible)
+	local syncToRobloxRef = useLatest(options.syncToRoblox ~= false)
+	React.useEffect(function()
+		local nodeId = registerFocusNode({
+			scopeId = scopeId,
+			getGuiObject = function()
+				return options.ref.current
+			end,
+			getDisabled = function()
+				local _condition_1 = disabledRef.current
+				if not _condition_1 then
+					local _result = getDisabledRef.current
+					if _result ~= nil then
+						_result = _result()
+					end
+					_condition_1 = _result == true
+				end
+				return _condition_1
+			end,
+			getVisible = function()
+				local _result = getVisibleRef.current
+				if _result ~= nil then
+					_result = _result()
+				end
+				return _result
+			end,
+			getSyncToRoblox = function()
+				return syncToRobloxRef.current
+			end,
+		})
+		nodeIdRef.current = nodeId
+		return function()
+			unregisterFocusNode(nodeId)
+			nodeIdRef.current = nil
+		end
+	end, { options.ref, scopeId })
+	return nodeIdRef
+end
+return {
+	useFocusNode = useFocusNode,
+}

package/out/index.d.ts

@@ -1,4 +1,8 @@
 export * from "./context";
+export * from "./focus/context";
+export * from "./focus/focusManager";
+export * from "./focus/useFocusNode";
+export * from "./orderedSelection";
 export { default as React } from "./react";
 export { default as ReactRoblox } from "./reactRoblox";
 export * from "./refs";

package/out/init.luau

@@ -4,6 +4,18 @@ local exports = {}
 for _k, _v in TS.import(script, script, "context") or {} do
 	exports[_k] = _v
 end
+for _k, _v in TS.import(script, script, "focus", "context") or {} do
+	exports[_k] = _v
+end
+for _k, _v in TS.import(script, script, "focus", "focusManager") or {} do
+	exports[_k] = _v
+end
+for _k, _v in TS.import(script, script, "focus", "useFocusNode") or {} do
+	exports[_k] = _v
+end
+for _k, _v in TS.import(script, script, "orderedSelection") or {} do
+	exports[_k] = _v
+end
 exports.React = TS.import(script, script, "react").default
 exports.ReactRoblox = TS.import(script, script, "reactRoblox").default
 for _k, _v in TS.import(script, script, "refs") or {} do

package/out/orderedSelection.d.ts

@@ -0,0 +1,16 @@
+import type React from "@rbxts/react";
+export type OrderedSelectionDirection = -1 | 1;
+export type OrderedSelectionEntry = {
+    id: number;
+    order: number;
+    ref: React.MutableRefObject<GuiObject | undefined>;
+    getDisabled?: () => boolean;
+    getVisible?: () => boolean;
+};
+export declare function getOrderedSelectionEntries<T extends OrderedSelectionEntry>(entries: Array<T>): T[];
+export declare function isOrderedSelectionEntryAvailable(entry: OrderedSelectionEntry): boolean;
+export declare function findOrderedSelectionEntry<T extends OrderedSelectionEntry>(entries: Array<T>, predicate: (entry: T) => boolean): T | undefined;
+export declare function getCurrentOrderedSelectionEntry<T extends OrderedSelectionEntry>(entries: Array<T>): T | undefined;
+export declare function getFirstOrderedSelectionEntry<T extends OrderedSelectionEntry>(entries: Array<T>): T | undefined;
+export declare function getRelativeOrderedSelectionEntry<T extends OrderedSelectionEntry>(entries: Array<T>, currentId: number | undefined, direction: OrderedSelectionDirection): T | undefined;
+export declare function focusOrderedSelectionEntry(entry: OrderedSelectionEntry | undefined): GuiObject | undefined;

package/out/orderedSelection.luau

@@ -0,0 +1,148 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _focusManager = TS.import(script, script.Parent, "focus", "focusManager")
+local focusManagedGuiObject = _focusManager.focusGuiObject
+local getFocusedGuiObject = _focusManager.getFocusedGuiObject
+local function isEntryVisible(entry)
+	local target = entry.ref.current
+	if not target then
+		return false
+	end
+	if entry.getVisible and not entry.getVisible() then
+		return false
+	end
+	return target.Visible
+end
+local function getOrderedSelectionEntries(entries)
+	local _array = {}
+	local _length = #_array
+	table.move(entries, 1, #entries, _length + 1, _array)
+	local ordered = _array
+	table.sort(ordered, function(left, right)
+		return left.order < right.order
+	end)
+	return ordered
+end
+local function isOrderedSelectionEntryAvailable(entry)
+	local target = entry.ref.current
+	if not target then
+		return false
+	end
+	local _result = entry.getDisabled
+	if _result ~= nil then
+		_result = _result()
+	end
+	if _result == true then
+		return false
+	end
+	if not isEntryVisible(entry) then
+		return false
+	end
+	return target.Selectable
+end
+local function findOrderedSelectionEntry(entries, predicate)
+	local _exp = getOrderedSelectionEntries(entries)
+	-- ▼ ReadonlyArray.find ▼
+	local _callback = function(entry)
+		return predicate(entry) and isOrderedSelectionEntryAvailable(entry)
+	end
+	local _result
+	for _i, _v in _exp do
+		if _callback(_v, _i - 1, _exp) == true then
+			_result = _v
+			break
+		end
+	end
+	-- ▲ ReadonlyArray.find ▲
+	return _result
+end
+local function getCurrentOrderedSelectionEntry(entries)
+	local current = getFocusedGuiObject()
+	if not current then
+		return nil
+	end
+	local _exp = getOrderedSelectionEntries(entries)
+	-- ▼ ReadonlyArray.find ▼
+	local _callback = function(entry)
+		return entry.ref.current == current and isOrderedSelectionEntryAvailable(entry)
+	end
+	local _result
+	for _i, _v in _exp do
+		if _callback(_v, _i - 1, _exp) == true then
+			_result = _v
+			break
+		end
+	end
+	-- ▲ ReadonlyArray.find ▲
+	return _result
+end
+local function getFirstOrderedSelectionEntry(entries)
+	local _exp = getOrderedSelectionEntries(entries)
+	-- ▼ ReadonlyArray.find ▼
+	local _result
+	for _i, _v in _exp do
+		if isOrderedSelectionEntryAvailable(_v, _i - 1, _exp) == true then
+			_result = _v
+			break
+		end
+	end
+	-- ▲ ReadonlyArray.find ▲
+	return _result
+end
+local function getRelativeOrderedSelectionEntry(entries, currentId, direction)
+	local _exp = getOrderedSelectionEntries(entries)
+	-- ▼ ReadonlyArray.filter ▼
+	local _newValue = {}
+	local _length = 0
+	for _k, _v in _exp do
+		if isOrderedSelectionEntryAvailable(_v, _k - 1, _exp) == true then
+			_length += 1
+			_newValue[_length] = _v
+		end
+	end
+	-- ▲ ReadonlyArray.filter ▲
+	local selectableEntries = _newValue
+	if #selectableEntries == 0 then
+		return nil
+	end
+	local _result
+	if currentId ~= nil then
+		-- ▼ ReadonlyArray.findIndex ▼
+		local _callback = function(entry)
+			return entry.id == currentId
+		end
+		local _result_1 = -1
+		for _i, _v in selectableEntries do
+			if _callback(_v, _i - 1, selectableEntries) == true then
+				_result_1 = _i - 1
+				break
+			end
+		end
+		-- ▲ ReadonlyArray.findIndex ▲
+		_result = _result_1
+	else
+		_result = -1
+	end
+	local currentIndex = _result
+	if currentIndex == -1 then
+		return if direction > 0 then selectableEntries[1] else selectableEntries[#selectableEntries]
+	end
+	local nextIndex = math.clamp(currentIndex + direction, 0, #selectableEntries - 1)
+	return selectableEntries[nextIndex + 1]
+end
+local function focusOrderedSelectionEntry(entry)
+	local _result = entry
+	if _result ~= nil then
+		_result = _result.ref.current
+	end
+	return focusManagedGuiObject(_result)
+end
+return {
+	getOrderedSelectionEntries = getOrderedSelectionEntries,
+	isOrderedSelectionEntryAvailable = isOrderedSelectionEntryAvailable,
+	findOrderedSelectionEntry = findOrderedSelectionEntry,
+	getCurrentOrderedSelectionEntry = getCurrentOrderedSelectionEntry,
+	getFirstOrderedSelectionEntry = getFirstOrderedSelectionEntry,
+	getRelativeOrderedSelectionEntry = getRelativeOrderedSelectionEntry,
+	focusOrderedSelectionEntry = focusOrderedSelectionEntry,
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lattice-ui/core",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "private": false,
   "main": "out/init.luau",
   "types": "out/index.d.ts",