@nrbx/topbar-components 1.1.14 → 1.2.0

package/README.md

@@ -55,32 +55,30 @@ Instantiate `<TopbarProvider />` to be a root of your topbar component tree.
 </TopbarProvider>
 ```
 
-#### Positioning icons with dock containers
+Icons without a `position` prop default to the **left** dock.
 
-Icons placed directly inside `<TopbarProvider>` default to the left side. Use the dock container components to position icons at the center or right of the bar:
+#### Positioning icons with the `position` prop
+
+Use the `position` prop on `<Icon>` components to automatically route them into the left, centre, or right dock:
 
 ```tsx
 <TopbarProvider>
-    <LeftDock>
-        <Icon text="Home" />
-        <Icon text="Settings" />
-    </LeftDock>
-    <CenterDock>
-        <Icon text="Server Time" static />
-    </CenterDock>
-    <RightDock>
-        <Icon text="Profile" imageId="rbxassetid://..." />
-    </RightDock>
+    <Icon position="left" text="Home" />
+    <Icon position="left" text="Settings" />
+    <Icon position="centre" text="Server Time" static />
+    <Icon position="right" text="Profile" imageId="rbxassetid://..." />
 </TopbarProvider>
 ```
 
-| Container | Anchor | Purpose |
-|---|---|---|
-| `<LeftDock>` | left edge | Default - icons flow left-to-right from the left |
-| `<CenterDock>` | center (50%) | Centers icons in the bar |
-| `<RightDock>` | right edge | Right-aligns icons |
+All three docks render automatically — no manual dock wrappers needed.
 
-Each dock container renders its own horizontal list with the configured `iconSpacing` and vertical centering. Center and right docks automatically apply `iconGroupSpacing` for visual separation.
+| Position | Behaviour |
+|---|---|
+| `"left"` (default) | Icons flow left-to-right from the left edge |
+| `"centre"` | Centers icons in the bar |
+| `"right"` | Right-aligns icons |
+
+Dock containers (`<LeftDock>`, `<CenterDock>`, `<RightDock>`) are still available for advanced layouts requiring nested structure.
 
 #### Icon props: `static` and `disabled`
 
@@ -192,25 +190,37 @@ Use `<CustomDropdown>` when you need to show rich, arbitrary content in a dropdo
 
 Appearance is controlled via `stylesheet.customDropdown`.
 
-#### Overflow handler
+#### Automatic overflow
+
+`TopbarProvider` accepts an `overflowAmount` prop that caps the visible icons per dock:
+
+```tsx
+<TopbarProvider overflowAmount={4}>
+    <Icon text="Home" />
+    <Icon text="Settings" />
+    <Icon text="Profile" />
+    <Icon text="Messages" />
+    <Icon text="Help" />
+    {/* Icons beyond 4 in any dock collapse into a "⋯" overflow menu */}
+</TopbarProvider>
+```
 
-When you have many icons in a dock, wrap them in `<Overflow>` to automatically collapse extras into a "more" (⋯) dropdown:
+When `overflowAmount` is **omitted**, the provider automatically detects whether icons from different docks overlap and progressively overflows them to prevent visual collisions. Icons moved into overflow appear in a dropdown behind the "⋯" button.
+
+#### Manual overflow
+
+For advanced cases, you can still wrap icons directly in `<Overflow>` inside a dock container:
 
 ```tsx
 <LeftDock>
     <Overflow>
         <Icon text="Home" />
         <Icon text="Settings" />
-        <Icon text="Profile" />
-        <Icon text="Messages" />
-        <Icon text="Help" />
         {/* ... many more ... */}
     </Overflow>
 </LeftDock>
 ```
 
-Based on TopbarPlus v3's overflow handler.
-
 ### Stylesheets
 
 You can use stylesheets to override default properties of all components within.

package/out/components/icon.d.ts

@@ -91,6 +91,12 @@ export interface IconProps extends React.PropsWithChildren {
     onRightClick?: () => void;
     /** Function used to play click sounds. Receives the sound asset ID. */
     playSound?: (id: string) => void;
+    /**
+     * When placed as a direct child of `TopbarProvider`, this controls
+     * which dock the icon is automatically routed to.
+     * Defaults to `"left"`.
+     */
+    position?: 'left' | 'right' | 'centre';
 }
 /** Icon select/deselect state. */
 export type IconState = 'selected' | 'deselected';

package/out/components/overflow.luau

@@ -24,18 +24,17 @@ local function Overflow(_param)
 		return arr
 	end, { children })
 	local overflowCount = #childArray
-	local handleToggle = useCallback(function()
-		setExpanded(function(prev)
-			return not prev
-		end)
+	local handleToggle = useCallback(function(state)
+		setExpanded(state == "selected")
 	end, {})
 	if overflowCount == 0 then
 		return React.createElement(React.Fragment)
 	end
 	return React.createElement(Icon, {
 		imageId = "rbxassetid://6069276526",
-		static = false,
 		toggleStateOnClick = true,
+		defaultState = "deselected",
+		stateChanged = handleToggle,
 		contentPaddingX = 4,
 		contentPaddingY = 4,
 	}, expanded and (React.createElement("frame", {

package/out/components/provider.d.ts

@@ -1,11 +1,17 @@
 import React from '@rbxts/react';
 export type SelectionMode = 'Single' | 'Multiple';
 /** Docks icons to the left side of the topbar. */
-export declare function LeftDock({ children }: React.PropsWithChildren): React.JSX.Element;
+export declare function LeftDock({ children, frameRef }: React.PropsWithChildren & {
+    frameRef?: React.Ref<Frame>;
+}): React.JSX.Element;
 /** Docks icons to the center of the topbar. */
-export declare function CenterDock({ children }: React.PropsWithChildren): React.JSX.Element;
+export declare function CenterDock({ children, frameRef }: React.PropsWithChildren & {
+    frameRef?: React.Ref<Frame>;
+}): React.JSX.Element;
 /** Docks icons to the right side of the topbar. */
-export declare function RightDock({ children }: React.PropsWithChildren): React.JSX.Element;
+export declare function RightDock({ children, frameRef }: React.PropsWithChildren & {
+    frameRef?: React.Ref<Frame>;
+}): React.JSX.Element;
 interface ProviderProps extends React.PropsWithChildren {
     /**
      * How icon selection works across the topbar.
@@ -15,12 +21,23 @@ interface ProviderProps extends React.PropsWithChildren {
     selectionMode?: SelectionMode;
     /** When `true`, shows a "Beta" label if voice chat is enabled on the client. */
     gameVoiceChatEnabled?: boolean;
+    /**
+     * Maximum number of icons shown per dock before overflow kicks in.
+     * When set, icons beyond this limit are moved into an overflow dropdown.
+     * When `undefined`, auto-detects overflow by measuring dock sizes to
+     * prevent icons from different docks overlapping each other.
+     */
+    overflowAmount?: number;
 }
 /**
  * Root provider for the topbar system.
  *
  * Must wrap all topbar components. Manages global selection state,
  * gui inset tracking, and the topbar frame bounds.
+ *
+ * Icons with a `position` prop placed as direct children are
+ * automatically routed into the left, centre, or right dock.
+ * Icons without a `position` prop are rendered as-is.
  */
-export declare function TopbarProvider({ selectionMode, gameVoiceChatEnabled, children }: ProviderProps): React.JSX.Element;
+export declare function TopbarProvider({ selectionMode, gameVoiceChatEnabled, overflowAmount, children, }: ProviderProps): React.JSX.Element;
 export {};

package/out/components/provider.luau

@@ -2,6 +2,9 @@
 local TS = _G[script]
 local _react = TS.import(script, TS.getModule(script, "@rbxts", "react"))
 local React = _react
+local useEffect = _react.useEffect
+local useMemo = _react.useMemo
+local useRef = _react.useRef
 local useState = _react.useState
 local _context = TS.import(script, script.Parent.Parent, "context")
 local LocationContext = _context.LocationContext
@@ -9,6 +12,7 @@ local useStylesheet = _context.useStylesheet
 local useGuiInset = TS.import(script, script.Parent.Parent, "hooks", "use-gui-inset").useGuiInset
 local useVoicechatEnabled = TS.import(script, script.Parent.Parent, "hooks", "use-voicechat-enabled").useVoicechatEnabled
 local debugLog = TS.import(script, script.Parent.Parent, "utilities", "debug").debugLog
+local Overflow = TS.import(script, script.Parent, "overflow").Overflow
 --[[
 	*
 	 * Anchors children to a side of the topbar.
@@ -18,6 +22,7 @@ local debugLog = TS.import(script, script.Parent.Parent, "utilities", "debug").d
 local function DockFrame(props)
 	local stylesheet = useStylesheet().provider
 	return React.createElement("frame", {
+		ref = props.frameRef,
 		BackgroundTransparency = 1,
 		AnchorPoint = props.anchor,
 		Position = props.position,
@@ -36,7 +41,9 @@ end
 --* Docks icons to the left side of the topbar. 
 local function LeftDock(_param)
 	local children = _param.children
+	local frameRef = _param.frameRef
 	return React.createElement(DockFrame, {
+		frameRef = frameRef,
 		anchor = Vector2.new(0, 0.5),
 		position = UDim2.new(0, 0, 0.5, 0),
 		children = children,
@@ -45,8 +52,10 @@ end
 --* Docks icons to the center of the topbar. 
 local function CenterDock(_param)
 	local children = _param.children
+	local frameRef = _param.frameRef
 	local stylesheet = useStylesheet().provider
 	return React.createElement(DockFrame, {
+		frameRef = frameRef,
 		anchor = Vector2.new(0.5, 0.5),
 		position = UDim2.new(0.5, 0, 0.5, 0),
 		paddingLeft = UDim.new(0, stylesheet.iconGroupSpacing),
@@ -57,8 +66,10 @@ end
 --* Docks icons to the right side of the topbar. 
 local function RightDock(_param)
 	local children = _param.children
+	local frameRef = _param.frameRef
 	local stylesheet = useStylesheet().provider
 	return React.createElement(DockFrame, {
+		frameRef = frameRef,
 		anchor = Vector2.new(1, 0.5),
 		position = UDim2.new(1, 0, 0.5, 0),
 		paddingLeft = UDim.new(0, stylesheet.iconGroupSpacing),
@@ -71,6 +82,10 @@ end
 	 *
 	 * Must wrap all topbar components. Manages global selection state,
 	 * gui inset tracking, and the topbar frame bounds.
+	 *
+	 * Icons with a `position` prop placed as direct children are
+	 * automatically routed into the left, centre, or right dock.
+	 * Icons without a `position` prop are rendered as-is.
 	 
 ]]
 local function TopbarProvider(_param)
@@ -79,11 +94,169 @@ local function TopbarProvider(_param)
 		selectionMode = "Single"
 	end
 	local gameVoiceChatEnabled = _param.gameVoiceChatEnabled
+	local overflowAmount = _param.overflowAmount
 	local children = _param.children
 	local selectedIcons, setSelectedIcons = useState({})
 	local inset = useGuiInset()
 	local voiceChatEnabled = useVoicechatEnabled()
 	local stylesheet = useStylesheet().provider
+	local containerRef = useRef()
+	local leftDockRef = useRef()
+	local centerDockRef = useRef()
+	local rightDockRef = useRef()
+	local autoOverflow, setAutoOverflow = useState({
+		left = 0,
+		centre = 0,
+		right = 0,
+	})
+	--* Sort direct children into docks based on the `position` prop. Defaults to left. 
+	local sorted = useMemo(function()
+		local groups = {
+			left = {},
+			centre = {},
+			right = {},
+		}
+		local other = {}
+		for _, child in React.Children.toArray(children) do
+			if not React.isValidElement(child) then
+				continue
+			end
+			local _condition = (child.props).position
+			if _condition == nil then
+				_condition = "left"
+			end
+			local pos = _condition
+			if groups[pos] ~= nil then
+				local _exp = groups[pos]
+				table.insert(_exp, child)
+			else
+				table.insert(other, child)
+			end
+		end
+		return {
+			groups = groups,
+			other = other,
+		}
+	end, { children })
+	-- get overflow count for a dock
+	local getOverflowCount = function(dock, total)
+		if overflowAmount ~= nil then
+			return math.max(0, total - overflowAmount)
+		end
+		return autoOverflow[dock]
+	end
+	-- auto-detect overflow when overflowAmount is not set
+	useEffect(function()
+		if overflowAmount ~= nil then
+			return nil
+		end
+		local container = containerRef.current
+		if not container then
+			return nil
+		end
+		local check = function()
+			local leftFrame = leftDockRef.current
+			local centerFrame = centerDockRef.current
+			local rightFrame = rightDockRef.current
+			if not leftFrame or not centerFrame or not rightFrame then
+				return nil
+			end
+			local containerWidth = container.AbsoluteSize.X
+			local groupSpacing = stylesheet.iconGroupSpacing
+			local leftRightEdge = leftFrame.AbsolutePosition.X + leftFrame.AbsoluteSize.X
+			local centerLeftEdge = centerFrame.AbsolutePosition.X - centerFrame.AbsoluteSize.X / 2
+			local centerRightEdge = centerFrame.AbsolutePosition.X + centerFrame.AbsoluteSize.X / 2
+			local rightLeftEdge = rightFrame.AbsolutePosition.X - rightFrame.AbsoluteSize.X
+			local overlapThreshold = groupSpacing + 10
+			local leftOverflow = 0
+			local centreOverflow = 0
+			local rightOverflow = 0
+			if leftRightEdge + overlapThreshold > centerLeftEdge then
+				local overflowPixels = leftRightEdge + overlapThreshold - centerLeftEdge
+				local iconEstimate = 52
+				leftOverflow = math.max(1, math.ceil(overflowPixels / iconEstimate))
+			end
+			if centerRightEdge + overlapThreshold > rightLeftEdge then
+				local overflowPixels = centerRightEdge + overlapThreshold - rightLeftEdge
+				local iconEstimate = 52
+				local totalOverflow = math.max(1, math.ceil(overflowPixels / iconEstimate))
+				centreOverflow = math.ceil(totalOverflow / 2)
+				rightOverflow = totalOverflow - centreOverflow
+			end
+			if leftRightEdge > containerWidth - 10 then
+				local overflowPixels = leftRightEdge - containerWidth + 10
+				leftOverflow = math.max(leftOverflow, math.ceil(overflowPixels / 52))
+			end
+			if rightFrame.AbsolutePosition.X < 10 then
+				rightOverflow = math.max(rightOverflow, 1)
+			end
+			setAutoOverflow(function(prev)
+				if prev.left == leftOverflow and prev.centre == centreOverflow and prev.right == rightOverflow then
+					return prev
+				end
+				return {
+					left = leftOverflow,
+					centre = centreOverflow,
+					right = rightOverflow,
+				}
+			end)
+		end
+		-- Defer measurement to let layout complete
+		task.spawn(function()
+			return check()
+		end)
+		local connections = {}
+		for _, frame in { leftDockRef.current, centerDockRef.current, rightDockRef.current } do
+			if frame then
+				local _arg0 = frame:GetPropertyChangedSignal("AbsoluteSize"):Connect(function()
+					return task.spawn(function()
+						return check()
+					end)
+				end)
+				local _arg1 = frame:GetPropertyChangedSignal("AbsolutePosition"):Connect(function()
+					return task.spawn(function()
+						return check()
+					end)
+				end)
+				-- ▼ Array.push ▼
+				table.insert(connections, _arg0)
+				table.insert(connections, _arg1)
+				-- ▲ Array.push ▲
+			end
+		end
+		return function()
+			-- ▼ ReadonlyArray.forEach ▼
+			local _callback = function(c)
+				c:Disconnect()
+			end
+			for _k, _v in connections do
+				_callback(_v, _k - 1, connections)
+			end
+			-- ▲ ReadonlyArray.forEach ▲
+			return nil
+		end
+	end, { sorted, overflowAmount, stylesheet.iconGroupSpacing })
+	-- build dock content with optional overflow
+	local buildDockContent = function(icons, dock)
+		local total = #icons
+		local overflowCount = getOverflowCount(dock, total)
+		if overflowCount <= 0 then
+			return icons
+		end
+		local visibleCount = total - overflowCount
+		local visible = {}
+		local overflowed = {}
+		for i = 1, total do
+			if i <= visibleCount then
+				local _arg0 = icons[i]
+				table.insert(visible, _arg0)
+			else
+				local _arg0 = icons[i]
+				table.insert(overflowed, _arg0)
+			end
+		end
+		return React.createElement(React.createFragment, nil, visible, React.createElement(Overflow, nil, overflowed))
+	end
 	local hasBetaLabel = gameVoiceChatEnabled and voiceChatEnabled
 	local leftPadding = if hasBetaLabel then stylesheet.paddingLeft + 16 else stylesheet.paddingLeft
 	local rawHeight = inset.Height - stylesheet.insetHeightOffset
@@ -135,6 +308,7 @@ local function TopbarProvider(_param)
 			end,
 		},
 	}, React.createElement("frame", {
+		ref = containerRef,
 		BackgroundTransparency = stylesheet.backgroundTransparency,
 		BackgroundColor3 = stylesheet.backgroundColor,
 		Size = UDim2.fromOffset(inset.Width * stylesheet.sizeScale.X, frameHeight * stylesheet.sizeScale.Y),
@@ -145,7 +319,13 @@ local function TopbarProvider(_param)
 		PaddingRight = UDim.new(0, stylesheet.paddingRight),
 		PaddingTop = UDim.new(0, stylesheet.paddingTop),
 		PaddingBottom = UDim.new(0, stylesheet.paddingBottom),
-	}), children))
+	}), React.createElement(LeftDock, {
+		frameRef = leftDockRef,
+	}, buildDockContent(sorted.groups.left, "left")), React.createElement(CenterDock, {
+		frameRef = centerDockRef,
+	}, buildDockContent(sorted.groups.centre, "centre")), React.createElement(RightDock, {
+		frameRef = rightDockRef,
+	}, buildDockContent(sorted.groups.right, "right")), sorted.other))
 end
 return {
 	LeftDock = LeftDock,

package/out/index.d.ts

@@ -1,9 +1,8 @@
-export * from "./components/custom-dropdown";
-export * from "./components/dropdown";
-export * from "./components/icon";
-export * from "./components/notification";
-export * from "./components/overflow";
-export * from "./components/provider";
-export * from "./components/stylesheet";
-export * from "./components/tooltip";
-export * from "./hooks/use-toggle-key";
+export * from './components/custom-dropdown';
+export * from './components/dropdown';
+export * from './components/icon';
+export * from './components/overflow';
+export * from './components/provider';
+export * from './components/stylesheet';
+export * from './components/tooltip';
+export * from './hooks/use-toggle-key';

package/out/init.luau

@@ -10,9 +10,6 @@ end
 for _k, _v in TS.import(script, script, "components", "icon") or {} do
 	exports[_k] = _v
 end
-for _k, _v in TS.import(script, script, "components", "notification") or {} do
-	exports[_k] = _v
-end
 for _k, _v in TS.import(script, script, "components", "overflow") or {} do
 	exports[_k] = _v
 end

package/out/style.luau

@@ -66,6 +66,7 @@ local DefaultStylesheet = {
 		hover = noop,
 		unhover = noop,
 		children = {},
+		position = "left",
 	},
 	dropdown = {
 		maxWidth = 300,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nrbx/topbar-components",
-  "version": "1.1.14",
+  "version": "1.2.0",
   "main": "out/init.luau",
   "scripts": {
     "build": "rbxtsc",