@nrbx/topbar-components 1.2.3 → 1.3.0

package/README.md

@@ -1,6 +1,5 @@
 <div align="center" id="top">
-    <img src="https://github.com/nn140/Branding/blob/main/LogoWhite-Full.png?raw=true" alt="NN140.UK logo" width="800"/>
-    <img src="https://github.com/nn140/Branding/blob/main/LogoBlack-Full.png?raw=true" alt="NN140.UK logo" width="800"/>
+    <img src="https://r2.nrbx.nn140.uk/img/NRBX-Banner.png" alt="NRBX logo" width="1000"/>
     <br />
     <br />
     <img src="https://img.shields.io/badge/Stripe-Donate%20to%20support%20NN140.UK-1b1b1b?style=for-the-badge&labelColor=6860ff&logo=stripe&logoColor=ffffff&logoSize=auto&link=https%3A%2F%2Fdonate.stripe.com%2F9B6eVdbTd4n1a6H1yXa3u04&link=https%3A%2F%2Fdonate.stripe.com%2F9B6eVdbTd4n1a6H1yXa3u04" alt="Badge">
@@ -93,13 +92,27 @@ Dock containers (`<LeftDock>`, `<CenterDock>`, `<RightDock>`) are still availabl
 
 The disabled overlay transparency and color are configurable via the stylesheet `sizing` section.
 
+#### Click behaviour and the `toggle` prop
+
+By default an icon is a **single-click button**: clicking it briefly lights up the background (and darkens the label) and then animates back, firing `onClick` once. It does not change its selection state.
+
+```tsx
+<Icon text="Home" onClick={() => goHome()} />   {/* standard click button */}
+```
+
+To make an icon a persistent toggle, pass the `toggle` prop. Clicking it switches between selected and deselected: `selected` fires when toggled on (button stays lit) and `deselected` fires when toggled off.
+
+```tsx
+<Icon text="Mute" toggle selected={() => mute()} deselected={() => unmute()} />
+```
+
 #### 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.
 
 ```tsx
-<Icon text="Skins">
+<Icon text="Skins" toggle>
     <Dropdown selectionMode="Single">
         <Icon text="yellow" selected={() => chooseSkin("yellow")} />
         <Icon text="red" selected={() => chooseSkin("red")} />
@@ -107,7 +120,7 @@ Dropdowns & TopbarProvider have a property called `selectionMode`, which lets yo
 </Icon>
 ```
 
-Dropdowns **can be nested.**
+Because a dropdown stays open while its parent icon is selected, the parent must opt in to toggle behaviour with the `toggle` prop. Dropdowns **can be nested.**
 
 #### Hover animations
 
@@ -142,10 +155,10 @@ Badge styling (colors, position, corner radius, border) is controlled via `style
 
 #### Toggle keys
 
-Bind a keyboard key to toggle an icon on/off with the `toggleKey` prop:
+Bind a keyboard key to toggle an icon on/off with the `toggleKey` prop (requires the `toggle` prop):
 
 ```tsx
-<Icon text="Menu" toggleKey={Enum.KeyCode.M} toggleStateOnClick />
+<Icon text="Menu" toggleKey={Enum.KeyCode.M} toggle />
 ```
 
 Any `Enum.KeyCode` value works. The key binding only activates while the icon is mounted.
@@ -173,7 +186,7 @@ Tooltip appearance (colors, font, padding, border) is controlled via `stylesheet
 Use `<CustomDropdown>` when you need to show rich, arbitrary content in a dropdown panel - not just child `<Icon>` elements:
 
 ```tsx
-<Icon text="Info" toggleStateOnClick>
+<Icon text="Info" toggle>
     <CustomDropdown width={250} maxHeight={180}>
         <textlabel Text="Custom content here!" />
         <textbutton Text="A button" />
@@ -237,7 +250,7 @@ import { Stylesheet } from "@nrbx/topbar-components";
 }}>
     <TopbarProvider>
         <LeftDock>
-            <Icon text="Skins">
+            <Icon text="Skins" toggle>
                 <Dropdown selectionMode="Single">
                     <Icon text="yellow" selected={() => chooseSkin("yellow")} />
                     <Icon text="red" selected={() => chooseSkin("red")} />
@@ -382,6 +395,5 @@ Package is licensed under the MIT License.
     <img src="https://img.shields.io/badge/Stripe-Donate%20to%20Support%20NN140.UK%20(RECCURING)-1b1b1b?style=for-the-badge&labelColor=6860ff&logo=stripe&logoColor=ffffff&logoSize=auto&link=https%3A%2F%2Fdonate.stripe.com%2FdRm9ATe1laLpgv5b9xa3u05&link=https%3A%2F%2Fdonate.stripe.com%2FdRm9ATe1laLpgv5b9xa3u05" alt="Badge">
     <br />
     <br />
-    <img src="https://github.com/nn140/Branding/blob/main/LogoBlack-Full.png?raw=true" alt="NN140.UK logo" width="800"/>
-    <img src="https://github.com/nn140/Branding/blob/main/LogoWhite-Full.png?raw=true" alt="NN140.UK logo" width="800"/>
+    <img src="https://r2.nrbx.nn140.uk/img/NRBX-Banner.png" alt="NRBX logo" width="1000"/>
 </div>

package/out/components/icon.d.ts

@@ -55,8 +55,12 @@ export interface IconProps extends React.PropsWithChildren {
     textAlignment?: StateDependent<Enum.TextXAlignment>;
     /** Whether the label supports rich text markup. */
     richText?: StateDependent<boolean>;
-    /** When `true`, clicking the icon toggles between selected and deselected. */
-    toggleStateOnClick?: boolean;
+    /**
+     * When `true`, clicking the icon toggles between selected and deselected.
+     * When `false` (the default), clicking briefly lights the icon up and fires
+     * {@link onClick} once without changing the selection state.
+     */
+    toggle?: boolean;
     /** When `true`, the icon ignores all clicks, hover, and state changes. */
     static?: boolean;
     /** When `true`, the icon is dimmed and non-interactive. */
@@ -85,7 +89,7 @@ export interface IconProps extends React.PropsWithChildren {
     unhover?: () => void;
     /** Callback fired whenever the state changes (receives the new state). */
     stateChanged?: (state: IconState) => void;
-    /** Callback fired on left click (in addition to the built-in toggle). */
+    /** Callback fired on left click. */
     onClick?: () => void;
     /** Callback fired on right click. */
     onRightClick?: () => void;

package/out/components/icon.luau

@@ -33,7 +33,8 @@ local Notification = TS.import(script, script.Parent, "notification").Notificati
 	 * both states, or `{ deselected: T; selected: T }` to animate between them.
 	 
 ]]
-local ANIMATEABLE = { "backgroundColor", "backgroundTransparency", "imageColor", "imageTransparency", "textTransparency" }
+local ANIMATEABLE = { "backgroundColor", "backgroundTransparency", "imageColor", "imageTransparency", "textColor", "textTransparency" }
+local FLASH_DURATION = 0.35
 --* Icon select/deselect state. 
 --[[
 	*
@@ -61,6 +62,9 @@ local function Icon(componentProps)
 	local location = useLocation()
 	local id = useId()
 	local currentState, setState = useState(componentProps.forcedState or "deselected")
+	--* Transiently lights the icon up on a single click when not in toggle mode. 
+	local flash, setFlash = useState(false)
+	local flashTimer = useRef()
 	local hovered, setHovered = useState(false)
 	local hoverLift, hoverLiftMotion = useMotion(0)
 	local dropdownAnimating, setAnimationState = useState(false)
@@ -76,12 +80,13 @@ local function Icon(componentProps)
 		_object[_k] = _v
 	end
 	local sizing = _object
+	local animateState = if flash then "selected" else currentState
 	local _object_1 = table.clone(stylesheet.icon)
 	setmetatable(_object_1, nil)
 	for _k, _v in componentProps do
 		_object_1[_k] = _v
 	end
-	local animatedProps = useAnimateableProps(currentState, _object_1, unpack(ANIMATEABLE))
+	local animatedProps = useAnimateableProps(animateState, _object_1, unpack(ANIMATEABLE))
 	local _object_2 = table.clone(stylesheet.icon)
 	setmetatable(_object_2, nil)
 	for _k, _v in (style or {}) do
@@ -140,7 +145,7 @@ local function Icon(componentProps)
 			if props.static then
 				return nil
 			end
-			if stateful(props.toggleStateOnClick, currentState) then
+			if props.toggle then
 				setState(if currentState == "deselected" then "selected" else "deselected")
 			end
 		end)
@@ -227,6 +232,11 @@ local function Icon(componentProps)
 		local _vector2_1 = Vector2.new(0, if includeContents then contentSize.Y else 0)
 		location.registerChild(id, _vector2 + _vector2_1)
 	end, { currentState, contentSize.Y, dropdownAnimating, iconSize })
+	useUnmountEffect(function()
+		if flashTimer.current then
+			task.cancel(flashTimer.current)
+		end
+	end)
 	useUnmountEffect(function()
 		if props.static then
 			return nil
@@ -269,8 +279,17 @@ local function Icon(componentProps)
 				if props.static then
 					return nil
 				end
-				if stateful(props.toggleStateOnClick, currentState) then
+				if props.toggle then
 					setState(if currentState == "deselected" then "selected" else "deselected")
+				else
+					if flashTimer.current then
+						task.cancel(flashTimer.current)
+					end
+					setFlash(true)
+					flashTimer.current = task.delay(FLASH_DURATION, function()
+						flashTimer.current = nil
+						setFlash(false)
+					end)
 				end
 				props.onClick()
 				local soundId = stateful(props.leftClickSound, currentState)
@@ -333,7 +352,7 @@ local function Icon(componentProps)
 	})), currentText ~= nil and currentText ~= "" and (React.createElement("textlabel", {
 		FontFace = stateful(props.fontFace, currentState),
 		TextSize = stateful(props.textSize, currentState),
-		TextColor3 = stateful(props.textColor, currentState),
+		TextColor3 = animatedProps.textColor,
 		TextWrapped = false,
 		Size = UDim2.fromOffset(textBounds.X, 0),
 		AutomaticSize = Enum.AutomaticSize.Y,

package/out/components/overflow.luau

@@ -32,7 +32,7 @@ local function Overflow(_param)
 	end
 	return React.createElement(Icon, {
 		imageId = "rbxassetid://6069276526",
-		toggleStateOnClick = true,
+		toggle = true,
 		defaultState = "deselected",
 		stateChanged = handleToggle,
 		contentPaddingX = 4,

package/out/style.luau

@@ -49,7 +49,7 @@ local DefaultStylesheet = {
 		text = "",
 		defaultState = "deselected",
 		forcedState = "deselected",
-		toggleStateOnClick = true,
+		toggle = false,
 		static = false,
 		disabled = false,
 		toggleKey = Enum.KeyCode.None,
@@ -87,7 +87,7 @@ local DefaultStylesheet = {
 	provider = {
 		paddingLeft = 8,
 		paddingRight = 12,
-		paddingTop = 11,
+		paddingTop = 12,
 		paddingBottom = 0,
 		iconSpacing = 12,
 		backgroundTransparency = 1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nrbx/topbar-components",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "main": "out/init.luau",
   "scripts": {
     "build": "rbxtsc",
@@ -26,16 +26,16 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ninjaninja140/rbxts-topbar-components.git"
+    "url": "git+https://github.com/nrbx-ts/rbxts-topbar-components.git"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.5.7",
+    "@biomejs/biome": "^2.5.8",
     "@rbxts/compiler-types": "^3.0.0-types.0",
     "@rbxts/react": "^17.3.7-ts.2",
-    "@rbxts/types": "^1.0.942",
+    "@rbxts/types": "^1.0.943",
     "roblox-ts": "^3.0.0",
     "typescript": "^6.0.3"
   },