@nrbx/topbar-components 1.0.6 → 1.0.8

package/README.md

@@ -49,28 +49,60 @@ And this to your `tsconfig.json`
 
 Instantiate `<TopbarProvider />` to be a root of your topbar component tree.
 
-```jsx
+```tsx
 <TopbarProvider>
     <Icon text="Hello, World!" />
 </TopbarProvider>
 ```
 
-Every `<Icon />` can be in only two states `selected`, and `deselected`.
-You can conditionally apply properties based on icon's current state, by providing a state markup object:
+#### 📍 Positioning icons with dock containers
 
-```jsx
-<Icon text={{
-    selected: "Selected!",
-    deselected: "Deselected!",
-}} />
+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:
+
+```tsx
+<TopbarProvider>
+    <LeftDock>
+        <Icon text="Home" />
+        <Icon text="Settings" />
+    </LeftDock>
+    <CenterDock>
+        <Icon text="Server Time" static />
+    </CenterDock>
+    <RightDock>
+        <Icon text="Profile" imageId="rbxassetid://..." />
+    </RightDock>
+</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 |
+
+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.
+
+#### 🏷️ Icon props: `static` and `disabled`
+
+- **`static`** — turns the icon into a non-interactive label (no clicks, no hovers, no state toggling, no sounds)
+- **`disabled`** — dims the icon with a configurable semi-transparent overlay
+
+```tsx
+<Icon text="Read Only" static />       {/* label, not clickable */}
+<Icon text="Locked" disabled />         {/* dimmed */}
+<Icon text="Both" static disabled />    {/* dimmed label */}
 ```
 
-You can add a dropdown to an icon by mounting `<Dropdown />` component as it's child:
+The disabled overlay transparency and color are configurable via the stylesheet `sizing` section.
+
+#### 🔽 Dropdowns
+
+You can add a dropdown to an icon by mounting `<Dropdown />` component as it's child.
 Dropdowns & TopbarProvider have a property called `selectionMode`, which lets you specify how many icons can be selected at once.
 
-```jsx
+```tsx
 <Icon text="Skins">
-    <Dropdown selectionMode="single">
+    <Dropdown selectionMode="Single">
         <Icon text="yellow" selected={() => chooseSkin("yellow")} />
         <Icon text="red" selected={() => chooseSkin("red")} />
     </Dropdown>
@@ -81,22 +113,104 @@ Dropdowns **can be nested.**
 
 ### 🎨 Stylesheets
 
-You can use stylesheets to override default properties of all components within:
+You can use stylesheets to override default properties of all components within.
 Stylesheets are partial, and work like patches to already established default properties within the package:
 
-```jsx
+```tsx
+import { Stylesheet } from "@nrbx/topbar-components";
+
 <Stylesheet stylesheet={{
     icon: {
         textSize: 25,
         cornerRadius: new UDim(0.5, 0),
-    }
+    },
+}}>
+    <TopbarProvider>
+        <LeftDock>
+            <Icon text="Skins">
+                <Dropdown selectionMode="Single">
+                    <Icon text="yellow" selected={() => chooseSkin("yellow")} />
+                    <Icon text="red" selected={() => chooseSkin("red")} />
+                </Dropdown>
+            </Icon>
+        </LeftDock>
+    </TopbarProvider>
+</Stylesheet>
+```
+
+#### Complete stylesheet shape
+
+The stylesheet exposes the following sections for full control:
+
+```tsx
+<Stylesheet stylesheet={{
+    // ── Icon defaults (all IconProps) ──
+    icon: {
+        textSize: 20,
+        textColor: { selected: Color3.fromRGB(57, 60, 65), deselected: Color3.fromRGB(255, 255, 255) },
+        backgroundColor: { selected: Color3.fromRGB(245, 245, 245), deselected: Color3.fromRGB(0, 0, 0) },
+        backgroundTransparency: 0.3,
+        cornerRadius: new UDim(1, 0),
+        fontFace: new Font("rbxasset://fonts/families/GothamSSm.json", Enum.FontWeight.Medium, Enum.FontStyle.Normal),
+        static: false,
+        disabled: false,
+        // ... all other IconProps
+    },
+
+    // ── Dropdown defaults (all DropdownProps) ──
+    dropdown: {
+        maxWidth: 300,
+        minWidth: 200,
+        maxHeight: 200,
+        forceHeight: 32,
+        padding: new UDim(0, 2.5),
+        selectionMode: "Multiple",
+        // ... all other DropdownProps
+    },
+
+    // ── Provider frame ──
+    provider: {
+        paddingLeft: 8,           paddingRight: 12,
+        paddingTop: 11,           paddingBottom: 0,
+        iconSpacing: 12,          iconGroupSpacing: 0,
+        backgroundTransparency: 1,
+        anchorPoint: new Vector2(1, 0),
+        position: UDim2.fromScale(1, 0),
+        sizeScale: new Vector2(1, 1),
+        insetHeightOffset: 0,
+        forceFrameHeight: undefined,  // override auto height (e.g. 55)
+    },
+
+    // ── Icon internal sizing ──
+    sizing: {
+        iconHeight: undefined,    // explicit override
+        imagePadding: 6,
+        labelPadding: 6,
+        imageToTextSpacing: 6,
+        textMeasurementWidth: 99999,
+        minLabelWidthPadding: 12,
+        buttonLabelHeightFraction: 0.8,
+        disabledOverlayTransparency: 0.55,
+        disabledOverlayColor: new Color3(0, 0, 0),
+    },
+
+    // ── Dropdown surface theme ──
+    dropdownTheme: {
+        backgroundColor: new Color3(1, 1, 1),
+        backgroundTransparency: 0,
+        cornerRadius: new UDim(0, 0),
+        borderSize: 0,            borderColor: new Color3(0, 0, 0),
+        borderTransparency: 1,
+        position: UDim2.fromScale(0, 1),
+    },
+
+    // ── Animation ──
+    animation: {
+        dropdownTransitionSpeed: 10,
+        stateSpring: { tension: 400 },
+    },
 }}>
-    <Icon text="Skins">
-        <Dropdown selectionMode="single">
-            <Icon text="yellow" selected={() => chooseSkin("yellow")} />
-            <Icon text="red" selected={() => chooseSkin("red")} />
-        </Dropdown>
-    </Icon>
+    {/* children */}
 </Stylesheet>
 ```
 

package/out/components/icon.d.ts

@@ -1,5 +1,4 @@
 import React from '@rbxts/react';
-export type Dock = 'Left' | 'Center' | 'Right';
 export interface IconProps extends React.PropsWithChildren {
     backgroundTransparency?: StateDependent<number>;
     backgroundColor?: StateDependent<Color3>;
@@ -25,7 +24,6 @@ export interface IconProps extends React.PropsWithChildren {
     textAlignment?: StateDependent<Enum.TextXAlignment>;
     richText?: StateDependent<boolean>;
     toggleStateOnClick?: boolean;
-    dock?: Dock;
     /** When true, renders as a non-interactive label (no clicks, no hovers, no state changes) */
     static?: boolean;
     /** When true, dulls the text and icon with a dimming overlay */

package/out/components/provider.d.ts

@@ -1,10 +1,8 @@
 import React from '@rbxts/react';
-import type { Dock } from './icon';
 export type SelectionMode = 'Single' | 'Multiple';
-interface ContainerProps extends React.PropsWithChildren {
-    dock: Dock;
-}
-export declare function TopBarContainer({ dock, children }: ContainerProps): React.JSX.Element;
+export declare function LeftDock({ children }: React.PropsWithChildren): React.JSX.Element;
+export declare function CenterDock({ children }: React.PropsWithChildren): React.JSX.Element;
+export declare function RightDock({ children }: React.PropsWithChildren): React.JSX.Element;
 interface ProviderProps extends React.PropsWithChildren {
     selectionMode?: SelectionMode;
     gameVoiceChatEnabled?: boolean;

package/out/components/provider.luau

@@ -2,10 +2,6 @@
 local TS = _G[script]
 local _react = TS.import(script, TS.getModule(script, "@rbxts", "react"))
 local React = _react
-local createContext = _react.createContext
-local useContext = _react.useContext
-local useEffect = _react.useEffect
-local useMemo = _react.useMemo
 local useState = _react.useState
 local _context = TS.import(script, script.Parent.Parent, "context")
 local LocationContext = _context.LocationContext
@@ -13,136 +9,55 @@ 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
--- ── Dock registry — containers register their children by dock ──────────────
-local DockRegistryContext = createContext(nil)
-local function useDockRegistry()
-	return useContext(DockRegistryContext)
+-- ── Dock container components ───────────────────────────────────────────────
+local function DockFrame(props)
+	local stylesheet = useStylesheet().provider
+	return React.createElement("frame", {
+		BackgroundTransparency = 1,
+		AnchorPoint = props.anchor,
+		Position = props.position,
+		Size = UDim2.fromScale(0, 1),
+		AutomaticSize = Enum.AutomaticSize.X,
+	}, (props.paddingLeft ~= nil or props.paddingRight ~= nil) and (React.createElement("uipadding", {
+		PaddingLeft = props.paddingLeft or UDim.new(0, 0),
+		PaddingRight = props.paddingRight or UDim.new(0, 0),
+	})), React.createElement("uilistlayout", {
+		FillDirection = Enum.FillDirection.Horizontal,
+		SortOrder = Enum.SortOrder.LayoutOrder,
+		Padding = UDim.new(0, stylesheet.iconSpacing),
+		VerticalAlignment = Enum.VerticalAlignment.Center,
+	}), props.children)
 end
--- ── TopBarContainer ─────────────────────────────────────────────────────────
-local function TopBarContainer(_param)
-	local dock = _param.dock
+local function LeftDock(_param)
 	local children = _param.children
-	local registry = useDockRegistry()
-	local id = useMemo(function()
-		return math.random()
-	end, {})
-	useEffect(function()
-		registry:register(dock, id, children)
-		return function()
-			return registry:unregister(dock, id)
-		end
-	end, {})
-	return React.createElement(React.Fragment)
+	return React.createElement(DockFrame, {
+		anchor = Vector2.new(0, 0.5),
+		position = UDim2.new(0, 0, 0.5, 0),
+		children = children,
+	})
 end
--- ── Provider ────────────────────────────────────────────────────────────────
-local function useDockNodes()
-	local leftNodes, setLeftNodes = useState({})
-	local centerNodes, setCenterNodes = useState({})
-	local rightNodes, setRightNodes = useState({})
-	local registry = useMemo(function()
-		return {
-			register = function(dock, id, element)
-				local entry = {
-					id = id,
-					element = element,
-				}
-				debugLog(`DockRegistry: register id={id} dock="{dock}"`)
-				if dock == "Center" then
-					setCenterNodes(function(prev)
-						local _array = {}
-						local _length = #_array
-						local _prevLength = #prev
-						table.move(prev, 1, _prevLength, _length + 1, _array)
-						_length += _prevLength
-						_array[_length + 1] = entry
-						return _array
-					end)
-				elseif dock == "Right" then
-					setRightNodes(function(prev)
-						local _array = {}
-						local _length = #_array
-						local _prevLength = #prev
-						table.move(prev, 1, _prevLength, _length + 1, _array)
-						_length += _prevLength
-						_array[_length + 1] = entry
-						return _array
-					end)
-				else
-					setLeftNodes(function(prev)
-						local _array = {}
-						local _length = #_array
-						local _prevLength = #prev
-						table.move(prev, 1, _prevLength, _length + 1, _array)
-						_length += _prevLength
-						_array[_length + 1] = entry
-						return _array
-					end)
-				end
-			end,
-			unregister = function(dock, id)
-				debugLog(`DockRegistry: unregister id={id} dock="{dock}"`)
-				if dock == "Center" then
-					setCenterNodes(function(prev)
-						-- ▼ ReadonlyArray.filter ▼
-						local _newValue = {}
-						local _callback = function(e)
-							return e.id ~= id
-						end
-						local _length = 0
-						for _k, _v in prev do
-							if _callback(_v, _k - 1, prev) == true then
-								_length += 1
-								_newValue[_length] = _v
-							end
-						end
-						-- ▲ ReadonlyArray.filter ▲
-						return _newValue
-					end)
-				elseif dock == "Right" then
-					setRightNodes(function(prev)
-						-- ▼ ReadonlyArray.filter ▼
-						local _newValue = {}
-						local _callback = function(e)
-							return e.id ~= id
-						end
-						local _length = 0
-						for _k, _v in prev do
-							if _callback(_v, _k - 1, prev) == true then
-								_length += 1
-								_newValue[_length] = _v
-							end
-						end
-						-- ▲ ReadonlyArray.filter ▲
-						return _newValue
-					end)
-				else
-					setLeftNodes(function(prev)
-						-- ▼ ReadonlyArray.filter ▼
-						local _newValue = {}
-						local _callback = function(e)
-							return e.id ~= id
-						end
-						local _length = 0
-						for _k, _v in prev do
-							if _callback(_v, _k - 1, prev) == true then
-								_length += 1
-								_newValue[_length] = _v
-							end
-						end
-						-- ▲ ReadonlyArray.filter ▲
-						return _newValue
-					end)
-				end
-			end,
-		}
-	end, {})
-	return {
-		registry = registry,
-		leftNodes = leftNodes,
-		centerNodes = centerNodes,
-		rightNodes = rightNodes,
-	}
+local function CenterDock(_param)
+	local children = _param.children
+	local stylesheet = useStylesheet().provider
+	return React.createElement(DockFrame, {
+		anchor = Vector2.new(0.5, 0.5),
+		position = UDim2.new(0.5, 0, 0.5, 0),
+		paddingLeft = UDim.new(0, stylesheet.iconGroupSpacing),
+		paddingRight = UDim.new(0, stylesheet.iconGroupSpacing),
+		children = children,
+	})
 end
+local function RightDock(_param)
+	local children = _param.children
+	local stylesheet = useStylesheet().provider
+	return React.createElement(DockFrame, {
+		anchor = Vector2.new(1, 0.5),
+		position = UDim2.new(1, 0, 0.5, 0),
+		paddingLeft = UDim.new(0, stylesheet.iconGroupSpacing),
+		children = children,
+	})
+end
+-- ── Provider ────────────────────────────────────────────────────────────────
 local function TopbarProvider(_param)
 	local selectionMode = _param.selectionMode
 	if selectionMode == nil then
@@ -154,117 +69,12 @@ local function TopbarProvider(_param)
 	local inset = useGuiInset()
 	local voiceChatEnabled = useVoicechatEnabled()
 	local stylesheet = useStylesheet().provider
-	local _binding = useDockNodes()
-	local registry = _binding.registry
-	local leftNodes = _binding.leftNodes
-	local centerNodes = _binding.centerNodes
-	local rightNodes = _binding.rightNodes
 	local hasBetaLabel = gameVoiceChatEnabled and voiceChatEnabled
 	local leftPadding = if hasBetaLabel then stylesheet.paddingLeft + 16 else stylesheet.paddingLeft
 	local rawHeight = inset.Height - stylesheet.insetHeightOffset
 	local frameHeight = if stylesheet.forceFrameHeight ~= nil then stylesheet.forceFrameHeight else rawHeight
 	debugLog(`TopbarProvider frame: inset.Height={inset.Height}, inset.Width={inset.Width}`, `insetHeightOffset={stylesheet.insetHeightOffset}`, `rawHeight={rawHeight}`, `forceFrameHeight={stylesheet.forceFrameHeight}`, `finalHeight={frameHeight}`, `sizeScale=({stylesheet.sizeScale.X}, {stylesheet.sizeScale.Y})`)
-	local hasCenter = #centerNodes > 0
-	local hasRight = #rightNodes > 0
-	local _exp = React.createElement("uipadding", {
-		key = "UIPadding",
-		PaddingLeft = UDim.new(0, leftPadding),
-		PaddingRight = UDim.new(0, stylesheet.paddingRight),
-		PaddingTop = UDim.new(0, stylesheet.paddingTop),
-		PaddingBottom = UDim.new(0, stylesheet.paddingBottom),
-	})
-	local _exp_1 = React.createElement("uilistlayout", {
-		FillDirection = Enum.FillDirection.Horizontal,
-		SortOrder = Enum.SortOrder.LayoutOrder,
-		Padding = UDim.new(0, stylesheet.iconSpacing),
-		VerticalAlignment = Enum.VerticalAlignment.Center,
-	})
-	local _exp_2 = children
-	-- ▼ ReadonlyArray.map ▼
-	local _newValue = table.create(#leftNodes)
-	local _callback = function(entry)
-		return React.createElement(React.Fragment, {
-			key = entry.id,
-		}, entry.element)
-	end
-	for _k, _v in leftNodes do
-		_newValue[_k] = _callback(_v, _k - 1, leftNodes)
-	end
-	-- ▲ ReadonlyArray.map ▲
-	local _exp_3 = React.createElement("frame", {
-		key = "LeftDock",
-		BackgroundTransparency = 1,
-		AnchorPoint = Vector2.new(0, 0.5),
-		Position = UDim2.new(0, 0, 0.5, 0),
-		Size = UDim2.fromScale(0, 1),
-		AutomaticSize = Enum.AutomaticSize.X,
-	}, _exp_1, _exp_2, _newValue)
-	local _condition = hasCenter
-	if _condition then
-		local _exp_4 = React.createElement("uipadding", {
-			PaddingLeft = UDim.new(0, stylesheet.iconGroupSpacing),
-			PaddingRight = UDim.new(0, stylesheet.iconGroupSpacing),
-		})
-		local _exp_5 = React.createElement("uilistlayout", {
-			FillDirection = Enum.FillDirection.Horizontal,
-			SortOrder = Enum.SortOrder.LayoutOrder,
-			Padding = UDim.new(0, stylesheet.iconSpacing),
-			VerticalAlignment = Enum.VerticalAlignment.Center,
-		})
-		-- ▼ ReadonlyArray.map ▼
-		local _newValue_1 = table.create(#centerNodes)
-		local _callback_1 = function(entry)
-			return React.createElement(React.Fragment, {
-				key = entry.id,
-			}, entry.element)
-		end
-		for _k, _v in centerNodes do
-			_newValue_1[_k] = _callback_1(_v, _k - 1, centerNodes)
-		end
-		-- ▲ ReadonlyArray.map ▲
-		_condition = (React.createElement("frame", {
-			key = "CenterDock",
-			BackgroundTransparency = 1,
-			AnchorPoint = Vector2.new(0.5, 0.5),
-			Position = UDim2.new(0.5, 0, 0.5, 0),
-			Size = UDim2.fromScale(0, 1),
-			AutomaticSize = Enum.AutomaticSize.X,
-		}, _exp_4, _exp_5, _newValue_1))
-	end
-	local _condition_1 = hasRight
-	if _condition_1 then
-		local _exp_4 = React.createElement("uipadding", {
-			PaddingLeft = UDim.new(0, stylesheet.iconGroupSpacing),
-		})
-		local _exp_5 = React.createElement("uilistlayout", {
-			FillDirection = Enum.FillDirection.Horizontal,
-			SortOrder = Enum.SortOrder.LayoutOrder,
-			Padding = UDim.new(0, stylesheet.iconSpacing),
-			VerticalAlignment = Enum.VerticalAlignment.Center,
-		})
-		-- ▼ ReadonlyArray.map ▼
-		local _newValue_1 = table.create(#rightNodes)
-		local _callback_1 = function(entry)
-			return React.createElement(React.Fragment, {
-				key = entry.id,
-			}, entry.element)
-		end
-		for _k, _v in rightNodes do
-			_newValue_1[_k] = _callback_1(_v, _k - 1, rightNodes)
-		end
-		-- ▲ ReadonlyArray.map ▲
-		_condition_1 = (React.createElement("frame", {
-			key = "RightDock",
-			BackgroundTransparency = 1,
-			AnchorPoint = Vector2.new(1, 0.5),
-			Position = UDim2.new(1, 0, 0.5, 0),
-			Size = UDim2.fromScale(0, 1),
-			AutomaticSize = Enum.AutomaticSize.X,
-		}, _exp_4, _exp_5, _newValue_1))
-	end
-	return React.createElement(DockRegistryContext.Provider, {
-		value = registry,
-	}, React.createElement(LocationContext.Provider, {
+	return React.createElement(LocationContext.Provider, {
 		value = {
 			type = "provider",
 			selectedIcons = selectedIcons,
@@ -283,29 +93,29 @@ local function TopbarProvider(_param)
 				end)
 			end,
 			iconDeselected = function(iconId)
-				local _condition_2 = selectionMode == "Single"
-				if _condition_2 then
+				local _condition = selectionMode == "Single"
+				if _condition then
 					local _iconId = iconId
-					_condition_2 = table.find(selectedIcons, _iconId) ~= nil
+					_condition = table.find(selectedIcons, _iconId) ~= nil
 				end
-				if _condition_2 then
+				if _condition then
 					return setSelectedIcons({})
 				end
 				return setSelectedIcons(function(icons)
 					-- ▼ ReadonlyArray.filter ▼
-					local _newValue_1 = {}
-					local _callback_1 = function(T)
+					local _newValue = {}
+					local _callback = function(T)
 						return T ~= iconId
 					end
 					local _length = 0
 					for _k, _v in icons do
-						if _callback_1(_v, _k - 1, icons) == true then
+						if _callback(_v, _k - 1, icons) == true then
 							_length += 1
-							_newValue_1[_length] = _v
+							_newValue[_length] = _v
 						end
 					end
 					-- ▲ ReadonlyArray.filter ▲
-					return _newValue_1
+					return _newValue
 				end)
 			end,
 		},
@@ -316,9 +126,17 @@ local function TopbarProvider(_param)
 		Size = UDim2.fromOffset(inset.Width * stylesheet.sizeScale.X, frameHeight * stylesheet.sizeScale.Y),
 		AnchorPoint = stylesheet.anchorPoint,
 		Position = stylesheet.position,
-	}, _exp, _exp_3, _condition, _condition_1)))
+	}, React.createElement("uipadding", {
+		key = "UIPadding",
+		PaddingLeft = UDim.new(0, leftPadding),
+		PaddingRight = UDim.new(0, stylesheet.paddingRight),
+		PaddingTop = UDim.new(0, stylesheet.paddingTop),
+		PaddingBottom = UDim.new(0, stylesheet.paddingBottom),
+	}), children))
 end
 return {
-	TopBarContainer = TopBarContainer,
+	LeftDock = LeftDock,
+	CenterDock = CenterDock,
+	RightDock = RightDock,
 	TopbarProvider = TopbarProvider,
 }

package/out/style.luau

@@ -48,7 +48,6 @@ local DefaultStylesheet = {
 		defaultState = "deselected",
 		forcedState = "deselected",
 		toggleStateOnClick = true,
-		dock = "Left",
 		static = false,
 		disabled = false,
 		selected = noop,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nrbx/topbar-components",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "main": "out/init.lua",
   "scripts": {
     "build": "rbxtsc",