@nrbx/topbar-components 1.0.11 → 1.1.0

package/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 wad4444
+Copyright (c) 2023 ninjaninja140 (forked from wad4444)
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights

package/README.md

@@ -15,7 +15,7 @@
 
 **Topbar Components** is a react component package that mimics [*topbar-plus*](https://devforum.roblox.com/t/v3-topbarplus-v300-construct-intuitive-topbar-icons-customise-them-with-themes-dropdowns-captions-labels-and-much-more/1017485) for [Roblox-TS](https://roblox-ts.com), with JSX markup support.
 
-## 📦 Installation
+## Installation
 
 **@nrbx/topbar-components** is available on NPM and can be installed with the following commands:
 
@@ -45,7 +45,7 @@ And this to your `tsconfig.json`
 "typeRoots": ["node_modules/@rbxts", "node_modules/@nrbx"],
 ```
 
-### ⚡ Quick Start
+### Quick Start
 
 Instantiate `<TopbarProvider />` to be a root of your topbar component tree.
 
@@ -55,7 +55,7 @@ Instantiate `<TopbarProvider />` to be a root of your topbar component tree.
 </TopbarProvider>
 ```
 
-#### 📍 Positioning icons with dock containers
+#### Positioning icons with dock containers
 
 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:
 
@@ -76,16 +76,16 @@ Icons placed directly inside `<TopbarProvider>` default to the left side. Use th
 
 | Container | Anchor | Purpose |
 |---|---|---|
-| `<LeftDock>` | left edge | Default — icons flow left-to-right from the left |
+| `<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`
+#### 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
+- **`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 */}
@@ -95,7 +95,7 @@ Each dock container renders its own horizontal list with the configured `iconSpa
 
 The disabled overlay transparency and color are configurable via the stylesheet `sizing` section.
 
-#### 🔽 Dropdowns
+#### 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.
@@ -111,7 +111,107 @@ Dropdowns & TopbarProvider have a property called `selectionMode`, which lets yo
 
 Dropdowns **can be nested.**
 
-### 🎨 Stylesheets
+#### Hover animations
+
+Icons can lift upward on hover for a subtle interactive feel. Enable or disable it globally via the stylesheet:
+
+```tsx
+<Stylesheet stylesheet={{
+    animation: {
+        hoverEnabled: true,   // turn hover lift on/off
+        hoverLift: 4,         // pixels to lift
+    },
+}}>
+    <TopbarProvider>
+        <Icon text="Hover Me" />
+    </TopbarProvider>
+</Stylesheet>
+```
+
+Hover lift uses the same spring configuration as state transitions (`animation.stateSpring`).
+
+#### Notification badges
+
+Add a red notification badge to any icon with the `notificationCount` prop. Counts over 99 display as `99+`. The badge hides automatically when the count is 0.
+
+```tsx
+<Icon text="Inbox" notificationCount={3} />
+<Icon text="Mail" notificationCount={150} />   {/* shows "99+" */}
+<Icon text="Clear" notificationCount={0} />     {/* badge hidden */}
+```
+
+Badge styling (colors, position, corner radius, border) is controlled via `stylesheet.notification`.
+
+#### Toggle keys
+
+Bind a keyboard key to toggle an icon on/off with the `toggleKey` prop:
+
+```tsx
+<Icon text="Menu" toggleKey={Enum.KeyCode.M} toggleStateOnClick />
+```
+
+Any `Enum.KeyCode` value works. The key binding only activates while the icon is mounted.
+
+#### Tooltips
+
+Wrap any element in a `<Tooltip>` to show a hover tooltip after a configurable delay:
+
+```tsx
+<Tooltip content="Go home" side="bottom" delayMs={500}>
+    <Icon imageId="rbxassetid://..." />
+</Tooltip>
+```
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `content` | `string` | required | Text displayed inside the tooltip |
+| `side` | `"top"` \| `"bottom"` \| `"left"` \| `"right"` | `"top"` | Which side of the child to appear on |
+| `delayMs` | `number` | stylesheet value | Milliseconds before the tooltip appears |
+
+Tooltip appearance (colors, font, padding, border) is controlled via `stylesheet.tooltip`.
+
+#### Custom Dropdowns
+
+Use `<CustomDropdown>` when you need to show rich, arbitrary content in a dropdown panel - not just child `<Icon>` elements:
+
+```tsx
+<Icon text="Info" toggleStateOnClick>
+    <CustomDropdown width={250} maxHeight={180}>
+        <textlabel Text="Custom content here!" />
+        <textbutton Text="A button" />
+    </CustomDropdown>
+</Icon>
+```
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `visible` | `boolean` | - | Whether the dropdown is open (usually driven by icon state) |
+| `width` | `number` | `200` | Width in pixels |
+| `maxHeight` | `number` | `200` | Max height before scrolling |
+| `position` | `UDim2` | stylesheet value | Position relative to the parent icon |
+
+Appearance is controlled via `stylesheet.customDropdown`.
+
+#### Overflow handler
+
+When you have many icons in a dock, wrap them in `<Overflow>` to automatically collapse extras into a "more" (⋯) dropdown:
+
+```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.
 Stylesheets are partial, and work like patches to already established default properties within the package:
@@ -144,7 +244,7 @@ The stylesheet exposes the following sections for full control:
 
 ```tsx
 <Stylesheet stylesheet={{
-    // ── Icon defaults (all IconProps) ──
+    // Icon defaults (all IconProps)
     icon: {
         textSize: 20,
         textColor: { selected: Color3.fromRGB(57, 60, 65), deselected: Color3.fromRGB(255, 255, 255) },
@@ -157,7 +257,7 @@ The stylesheet exposes the following sections for full control:
         // ... all other IconProps
     },
 
-    // ── Dropdown defaults (all DropdownProps) ──
+    // Dropdown defaults (all DropdownProps)
     dropdown: {
         maxWidth: 300,
         minWidth: 200,
@@ -168,7 +268,7 @@ The stylesheet exposes the following sections for full control:
         // ... all other DropdownProps
     },
 
-    // ── Provider frame ──
+    // Provider frame
     provider: {
         paddingLeft: 8,           paddingRight: 12,
         paddingTop: 11,           paddingBottom: 0,
@@ -181,12 +281,15 @@ The stylesheet exposes the following sections for full control:
         forceFrameHeight: undefined,  // override auto height (e.g. 55)
     },
 
-    // ── Icon internal sizing ──
+    // Icon internal sizing
     sizing: {
-        iconHeight: undefined,    // explicit override
+        iconHeight: undefined,       // explicit override
+        iconWidth: undefined,        // explicit override (auto-fits when undefined/0)
         imagePadding: 6,
         labelPadding: 6,
         imageToTextSpacing: 6,
+        contentPaddingX: 6,          // horizontal pad from button edge to content
+        contentPaddingY: 6,          // vertical pad from button edge to content
         textMeasurementWidth: 99999,
         minLabelWidthPadding: 12,
         buttonLabelHeightFraction: 0.8,
@@ -194,7 +297,7 @@ The stylesheet exposes the following sections for full control:
         disabledOverlayColor: new Color3(0, 0, 0),
     },
 
-    // ── Dropdown surface theme ──
+    // Dropdown surface theme
     dropdownTheme: {
         backgroundColor: new Color3(1, 1, 1),
         backgroundTransparency: 0,
@@ -204,17 +307,60 @@ The stylesheet exposes the following sections for full control:
         position: UDim2.fromScale(0, 1),
     },
 
-    // ── Animation ──
+    // Animation
     animation: {
         dropdownTransitionSpeed: 10,
         stateSpring: { tension: 400 },
+        hoverEnabled: true,           // whether icons lift on hover
+        hoverLift: 4,                 // pixels to lift
+    },
+
+    // Notification badge
+    notification: {
+        backgroundColor: Color3.fromRGB(255, 59, 48),
+        backgroundTransparency: 0,
+        textColor: new Color3(1, 1, 1),
+        textSize: 12,
+        fontFace: new Font("rbxasset://fonts/families/GothamSSm.json", Enum.FontWeight.Bold),
+        position: new UDim2(0.5, 4, 0, -4),
+        size: new UDim2(0, 18, 0, 18),
+        cornerRadius: new UDim(1, 0),
+        borderColor: new Color3(1, 1, 1),
+        borderTransparency: 0,
+    },
+
+    // Tooltip
+    tooltip: {
+        backgroundColor: new Color3(0.1, 0.1, 0.1),
+        backgroundTransparency: 0.2,
+        textColor: new Color3(1, 1, 1),
+        textSize: 14,
+        fontFace: new Font("rbxasset://fonts/families/GothamSSm.json", Enum.FontWeight.Medium),
+        cornerRadius: new UDim(0, 4),
+        borderColor: new Color3(0.4, 0.4, 0.4),
+        borderTransparency: 0,
+        borderSize: 1,
+        paddingX: 8,
+        paddingY: 4,
+        delayMs: 500,
+    },
+
+    // Custom dropdown
+    customDropdown: {
+        backgroundColor: new Color3(1, 1, 1),
+        backgroundTransparency: 0,
+        cornerRadius: new UDim(0, 6),
+        borderSize: 0,
+        borderColor: new Color3(0, 0, 0),
+        borderTransparency: 1,
+        position: UDim2.fromScale(0, 1),
     },
 }}>
     {/* children */}
 </Stylesheet>
 ```
 
-### 📝 License
+### License
 
 Package is licensed under the MIT License.
 

package/out/components/custom-dropdown.d.ts

@@ -0,0 +1,19 @@
+import React from '@rbxts/react';
+interface CustomDropdownProps extends React.PropsWithChildren {
+    /** Whether the dropdown is visible. Typically driven by parent icon state. */
+    visible: boolean;
+    /** Width of the dropdown in pixels. */
+    width?: number;
+    /** Maximum height before scrolling. */
+    maxHeight?: number;
+    /** Position relative to the parent icon. */
+    position?: UDim2;
+}
+/**
+ * A dropdown panel for arbitrary custom content (not just child icons).
+ *
+ * Use this when you need rich UI inside a dropdown — forms, text, images —
+ * rather than a list of `<Icon>` children. Animated open/closed with a spring.
+ */
+export declare function CustomDropdown({ visible, width, maxHeight, position, children }: CustomDropdownProps): React.JSX.Element;
+export {};

package/out/components/custom-dropdown.luau

@@ -0,0 +1,86 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local _pretty_react_hooks = TS.import(script, TS.getModule(script, "@rbxts", "pretty-react-hooks").out)
+local mapBinding = _pretty_react_hooks.mapBinding
+local useMotion = _pretty_react_hooks.useMotion
+local useMountEffect = _pretty_react_hooks.useMountEffect
+local _react = TS.import(script, TS.getModule(script, "@rbxts", "react"))
+local React = _react
+local useBinding = _react.useBinding
+local useRef = _react.useRef
+local useStylesheet = TS.import(script, script.Parent.Parent, "context").useStylesheet
+--[[
+	*
+	 * A dropdown panel for arbitrary custom content (not just child icons).
+	 *
+	 * Use this when you need rich UI inside a dropdown — forms, text, images —
+	 * rather than a list of `<Icon>` children. Animated open/closed with a spring.
+	 
+]]
+local function CustomDropdown(_param)
+	local visible = _param.visible
+	local width = _param.width
+	if width == nil then
+		width = 200
+	end
+	local maxHeight = _param.maxHeight
+	if maxHeight == nil then
+		maxHeight = 200
+	end
+	local position = _param.position
+	local children = _param.children
+	local stylesheet = useStylesheet()
+	local theme = stylesheet.customDropdown
+	local animation = stylesheet.animation
+	local transition, transitionMotion = useMotion(if visible then 1 else 0)
+	local contentSize, setContentSize = useBinding(Vector2.zero)
+	local frameRef = useRef()
+	React.useEffect(function()
+		transitionMotion:spring(if visible then 1 else 0, {
+			tension = animation.dropdownTransitionSpeed * 15,
+			friction = 26,
+		})
+	end, { visible })
+	useMountEffect(function()
+		local frame = frameRef.current
+		if not frame then
+			return nil
+		end
+		setContentSize(frame.AbsoluteCanvasSize)
+		local conn = frame:GetPropertyChangedSignal("AbsoluteCanvasSize"):Connect(function()
+			setContentSize(frame.AbsoluteCanvasSize)
+		end)
+		return function()
+			return conn:Disconnect()
+		end
+	end)
+	local pos = position or theme.position
+	return React.createElement("scrollingframe", {
+		ref = frameRef,
+		ClipsDescendants = true,
+		Size = mapBinding(transition, function(t)
+			return UDim2.fromOffset(width, t * math.min(contentSize:getValue().Y, maxHeight))
+		end),
+		BorderSizePixel = theme.borderSize,
+		BorderColor3 = theme.borderColor,
+		BackgroundColor3 = theme.backgroundColor,
+		BackgroundTransparency = theme.backgroundTransparency,
+		Position = pos,
+		CanvasSize = UDim2.fromOffset(0, contentSize:getValue().Y),
+		AutomaticCanvasSize = Enum.AutomaticSize.Y,
+		ScrollBarThickness = 5,
+		ScrollBarImageColor3 = Color3.new(1, 1, 1),
+		ScrollBarImageTransparency = 0.8,
+		ScrollingEnabled = false,
+		ZIndex = 30,
+	}, React.createElement("uicorner", {
+		CornerRadius = theme.cornerRadius,
+	}), React.createElement("uistroke", {
+		Color = theme.borderColor,
+		Transparency = theme.borderTransparency,
+		Thickness = theme.borderSize,
+	}), children)
+end
+return {
+	CustomDropdown = CustomDropdown,
+}

package/out/components/dropdown.d.ts

@@ -1,18 +1,38 @@
 import React from '@rbxts/react';
 import type { SelectionMode } from './provider';
+/** Properties accepted by {@link Dropdown}. */
 export interface DropdownProps extends React.PropsWithChildren {
+    /** Minimum width of the dropdown in pixels. */
     minWidth?: number;
+    /** Maximum height before the dropdown becomes scrollable. */
     maxHeight?: number;
+    /** Maximum width of the dropdown in pixels. */
     maxWidth?: number;
+    /** Vertical padding between child icons. */
     padding?: UDim;
+    /** Fixed height applied to child icons inside this dropdown. */
     forceHeight?: number;
+    /** Corner radius applied to child icons inside this dropdown. */
     iconCornerRadius?: UDim;
+    /** Scroll bar thickness in pixels. */
     scrollBarThickness?: number;
+    /** Scroll bar transparency (0 = opaque, 1 = invisible). */
     scrollBarTransparency?: number;
+    /** Image for the scroll bar top cap. */
     topImage?: string;
+    /** Image for the scroll bar bottom cap. */
     bottomImage?: string;
+    /** Image for the scroll bar middle segment. */
     midImage?: string;
+    /** Color applied to the scroll bar images. */
     scrollBarImageColor?: Color3;
+    /** Selection mode: `Single` deselects others, `Multiple` allows many. */
     selectionMode?: SelectionMode;
 }
+/**
+ * A dropdown menu that appears below its parent icon.
+ *
+ * Child `<Icon>` components placed inside automatically register and size
+ * themselves. The dropdown animates open/closed with a spring transition.
+ */
 export declare function Dropdown(componentProps: DropdownProps): React.JSX.Element;

package/out/components/dropdown.luau

@@ -13,6 +13,15 @@ local _context = TS.import(script, script.Parent.Parent, "context")
 local LocationContext = _context.LocationContext
 local useLocation = _context.useLocation
 local useStylesheet = _context.useStylesheet
+--* Properties accepted by {@link Dropdown}. 
+--[[
+	*
+	 * A dropdown menu that appears below its parent icon.
+	 *
+	 * Child `<Icon>` components placed inside automatically register and size
+	 * themselves. The dropdown animates open/closed with a spring transition.
+	 
+]]
 local function Dropdown(componentProps)
 	local location = useLocation()
 	local fullStylesheet = useStylesheet()
@@ -43,8 +52,9 @@ local function Dropdown(componentProps)
 	end, { contents, maxWidth, minWidth, stylesheet.padding.Offset })
 	useEffect(function()
 		location.setAnimationState(true)
-		transitionMotion:linear(if location.isVisible then 1 else 0, {
-			speed = fullStylesheet.animation.dropdownTransitionSpeed,
+		transitionMotion:spring(if location.isVisible then 1 else 0, {
+			tension = fullStylesheet.animation.dropdownTransitionSpeed * 15,
+			friction = 26,
 		})
 	end, { location.isVisible })
 	useMountEffect(function()
@@ -170,20 +180,15 @@ local function Dropdown(componentProps)
 		MidImage = props.midImage,
 		TopImage = props.topImage,
 		BottomImage = props.bottomImage,
-		key = "Dropdown",
 	}, React.createElement("uicorner", {
-		key = "DropdownCorner",
 		CornerRadius = fullStylesheet.dropdownTheme.cornerRadius,
 	}), React.createElement("uistroke", {
-		key = "DropdownStroke",
 		Thickness = fullStylesheet.dropdownTheme.borderSize,
 		Color = fullStylesheet.dropdownTheme.borderColor,
 		Transparency = fullStylesheet.dropdownTheme.borderTransparency,
 	}), props.children, isNested and React.createElement("uipadding", {
-		key = "UIPadding",
 		PaddingTop = stylesheet.padding,
 	}), React.createElement("uilistlayout", {
-		key = "UIListLayout",
 		SortOrder = Enum.SortOrder.LayoutOrder,
 		Padding = stylesheet.padding,
 	})))

package/out/components/icon.d.ts

@@ -1,47 +1,112 @@
 import React from '@rbxts/react';
 import { type Stylesheet } from '../style';
+/**
+ * Properties accepted by {@link Icon}.
+ *
+ * Most visual props accept a `StateDependent<T>` — either a single value for
+ * both states, or `{ deselected: T; selected: T }` to animate between them.
+ */
 export interface IconProps extends React.PropsWithChildren {
+    /** Background transparency of the button. Animated on state change. */
     backgroundTransparency?: StateDependent<number>;
+    /** Background color of the button. Animated on state change. */
     backgroundColor?: StateDependent<Color3>;
+    /** Asset ID or full asset string for the icon image. */
     imageId?: StateDependent<string>;
+    /** Color applied to the icon image. Animated on state change. */
     imageColor?: StateDependent<Color3>;
+    /** Color applied to the label text. */
     textColor?: StateDependent<Color3>;
+    /** Transparency of the icon image. Animated on state change. */
     imageTransparency?: StateDependent<number>;
+    /** Layout order used for horizontal sorting in docks. */
     layoutOrder?: StateDependent<number>;
+    /** Text displayed next to or instead of the image. */
     text?: StateDependent<string>;
+    /** Font size of the label text. */
     textSize?: StateDependent<number>;
+    /** Pixel offset added to the computed image size. Negative values shrink the image. */
     imageSizeOffset?: StateDependent<number>;
+    /** Offset into the source image to crop from. */
     imageRectOffset?: StateDependent<Vector2>;
+    /** Size of the crop region from the source image. */
     imageRectSize?: StateDependent<Vector2>;
+    /** Initial state when the icon first mounts. */
     defaultState?: IconState;
+    /** Font face used for the label text. */
     fontFace?: StateDependent<Font>;
+    /** Override that locks the icon to a specific state. */
     forcedState?: IconState;
+    /** Sound played on left click (asset ID or empty for none). */
     leftClickSound?: StateDependent<string>;
+    /** Sound played on right click (asset ID or empty for none). */
     rightClickSound?: StateDependent<string>;
+    /** Corner radius of the button. */
     cornerRadius?: StateDependent<UDim>;
+    /** Stroke transparency of the label text. */
     strokeTransparency?: StateDependent<number>;
+    /** Stroke color of the label text. */
     strokeColor?: StateDependent<Color3>;
+    /** Stroke thickness of the label text. */
     strokeThickness?: StateDependent<number>;
+    /** Horizontal text alignment within the label. */
     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, renders as a non-interactive label (no clicks, no hovers, no state changes) */
+    /** When `true`, the icon ignores all clicks, hover, and state changes. */
     static?: boolean;
-    /** When true, dulls the text and icon with a dimming overlay */
+    /** When `true`, the icon is dimmed and non-interactive. */
     disabled?: boolean;
-    /** Per-icon stylesheet overrides — merged above the global stylesheet but below explicit props */
+    /** Inline overrides for icon props and sizing values. */
     style?: Partial<IconProps & Stylesheet['sizing']>;
+    /** Explicit icon width in pixels. When undefined or `0`, auto-fits to content. */
+    iconWidth?: number;
+    /** Horizontal padding between the button edge and its content. */
+    contentPaddingX?: number;
+    /** Vertical padding between the button edge and its content. */
+    contentPaddingY?: number;
+    /** Gap between the image and the text label. */
+    imageToTextSpacing?: number;
+    /** KeyCode that toggles the icon when pressed. */
+    toggleKey?: Enum.KeyCode;
+    /** Shows a red notification badge with this count. Hides when `0` or `undefined`. */
+    notificationCount?: number;
+    /** Callback fired when the icon becomes selected. */
     selected?: () => void;
+    /** Callback fired when the icon becomes deselected. */
     deselected?: () => void;
+    /** Callback fired on mouse enter. */
     hover?: () => void;
+    /** Callback fired on mouse leave. */
     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). */
     onClick?: () => void;
+    /** Callback fired on right click. */
     onRightClick?: () => void;
+    /** Function used to play click sounds. Receives the sound asset ID. */
     playSound?: (id: string) => void;
 }
+/** Icon select/deselect state. */
 export type IconState = 'selected' | 'deselected';
+/**
+ * A value that can change with icon state.
+ * Pass a single value for both states, or `{ deselected, selected }` for
+ * separate values that animate on state transitions.
+ */
 export type StateDependent<T> = Record<IconState, T> | T;
+/** Extracts the inner type from a `StateDependent`. */
 export type FromStateDependent<T> = T extends StateDependent<infer U> ? U : T;
+/** Unique numeric identifier for an icon instance. */
 export type IconId = number;
+/**
+ * A single icon in the topbar.
+ *
+ * Supports an image, a text label, state-dependent styling, animated state
+ * transitions, hover lift, notification badges, toggle keys, and nested
+ * dropdown content.
+ */
 export declare function Icon(componentProps: IconProps): React.JSX.Element;