@rbxts/app-forge 0.0.3 → 0.0.6

package/README.md

@@ -0,0 +1,318 @@
+# AppForge — React App & Window Manager for roblox-ts
+
+AppForge is a UI/app orchestration system for React in Roblox, enabling:
+
+✔ App registration
+✔ Visibility & state control
+✔ App grouping
+✔ Exclusive UI modes
+✔ Rule-based interactions
+✔ Priority & layering
+✔ React-friendly state bindings
+
+---
+
+# 📦 Installation
+
+```bash
+npm i @rbxts/app-forge
+# or
+bun i @rbxts/app-forge
+```
+
+---
+
+# 🧩 Setup — REQUIRED
+
+### Create `global.d.ts`
+
+```ts
+declare global {
+ // All registered Apps by name
+ type AppNames = readonly ["HUD", "Inventory", "Shop", "SideButtons", "Pause"];
+
+ // Logical groupings of apps
+ type AppGroups = readonly ["HUD", "Panel", "Overlay"];
+
+ // Props that are injected into each App
+ interface AppProps {
+  player: Player;
+  target: GuiObject | Camera;
+  playerData: any;
+  events: any;
+  appManager: import("@rbxts/app-forge").default;
+ }
+
+ export {};
+}
+```
+
+> AppForge will now use your AppNames & AppProps as typed globals.
+
+---
+
+# 🚀 Initializing AppForge
+
+```ts
+import AppManager, { Render } from "@rbxts/app-forge";
+import { createPortal, createRoot } from "@rbxts/react-roblox";
+import React from "@rbxts/react";
+
+const manager = new AppManager();
+const root = createRoot(new Instance("Folder"));
+
+const props: AppProps = {
+ player: Players.LocalPlayer!,
+ target: new Instance("Folder"),
+ playerData: {},
+ events: {},
+ appManager: manager,
+};
+
+root.render(
+ createPortal(
+  <screengui ResetOnSpawn={false} ZIndexBehavior="Sibling">
+   <Render props={props} manager={manager} />
+  </screengui>,
+  Players.LocalPlayer!.WaitForChild("PlayerGui"),
+ ),
+);
+```
+
+> `Render` will automatically render ALL registered apps.
+
+---
+
+# 🧱 Creating an App
+
+```ts
+import { App, Args } from "@rbxts/app-forge";
+import React from "@rbxts/react";
+
+@App({
+ name: "SideButtons",
+ visible: true,
+})
+export default class SideButtons extends Args {
+ render() {
+  return (
+   <frame Size={UDim2.fromScale(1, 1)}>Side Buttons UI</frame>
+  );
+ }
+}
+```
+
+### ❗ Note
+
+`Args` automatically injects AppProps and more into `this`, such as:
+
+```ts
+this.Forge // This is the AppForge Manager Created
+this.name // The Name given on Element Creation
+this.props // Props passed through Render
+```
+
+You never manually `new` apps — AppForge constructs them automatically.
+
+---
+
+# 🕹 App Manager API
+
+```ts
+appManager.toggle("Inventory");
+appManager.set("Shop", true);
+appManager.set("HUD", false);
+const isShown = appManager.getState("Pause");
+const bind = appManager.getBind("Inventory");
+```
+
+---
+
+# 📐 Using `getBind()` in React
+
+```tsx
+return (
+ <frame Visible={props.appManager.getBind("Inventory")}>
+  Items…
+ </frame>
+);
+```
+
+Binds re-render automatically on visibility change.
+
+---
+
+# ⌨️ Hotkey Toggle Example
+
+```ts
+UserInputService.InputBegan.Connect((input) => {
+ if (input.KeyCode === Enum.KeyCode.I)
+  appManager.toggle("Inventory");
+});
+```
+
+---
+
+# ⚖️ APP RULES SYSTEM
+
+Rules control UI interaction & visibility behavior.
+
+| Rule | Effect |
+|---|---|
+| blockedBy | Prevents opening if another app is active |
+| blocks | Auto-closes another app when opened |
+| exclusive | Closes ALL other apps except same group |
+| groups | Logical grouping categories |
+| layer | (Coming soon — currently not functional) |
+
+---
+
+## `blockedBy`
+
+App cannot open if the listed apps are open.
+
+```ts
+@App({ name: "Inventory", rules: { blockedBy: "Shop" } })
+```
+
+Multiple:
+
+```ts
+@App({ name: "Inventory", rules: { blockedBy: ["Shop", "Trade"] } })
+```
+
+---
+
+## `blocks`
+
+Opening the app will hide other apps.
+
+```ts
+@App({ name: "Shop", rules: { blocks: "Inventory" } })
+```
+
+Multiple:
+
+```ts
+@App({ name: "Shop", rules: { blocks: ["Inventory", "TeamUI"] } })
+```
+
+---
+
+## `exclusive`
+
+For fullscreen apps:
+
+```ts
+@App({ name: "Pause", rules: { exclusive: true } })
+```
+
+When Pause opens:
+
+✔ Inventory closes
+✔ HUD closes
+✔ SideButtons closes
+✔ Everything except Core
+
+---
+
+## `groups`
+
+Apps inside the same group DO NOT block each other.
+
+```ts
+@App({ name: "HUD", rules: { groups: ["HUD"] } })
+@App({ name: "Crosshair", rules: { groups: ["HUD"] } })
+```
+
+These can both be open at the same time.
+
+---
+
+## `Core` Group
+
+Core apps are ALWAYS allowed and never auto-hidden.
+
+```ts
+@App({ name: "FPSCounter", rules: { groups: "Core" } })
+```
+
+This app will NEVER be closed by rules.
+
+---
+
+## `layer` *(not implemented yet)*
+
+> The `layer` property is part of the upcoming UI priority system.
+> Setting it currently does not affect rendering order.
+
+Example (for future readiness):
+
+```ts
+@App({ name: "DebugUI", rules: { layer: 999 } })
+```
+
+---
+
+# 🧪 Full Rules Example
+
+```ts
+@App({ name: "HUD", rules: { groups: ["HUD"] } })
+@App({ name: "Inventory", rules: { blockedBy: "Shop", groups: ["Panel"] } })
+@App({ name: "Shop", rules: { blocks: "Inventory", groups: ["Panel"] } })
+@App({ name: "Pause", rules: { exclusive: true } })
+@App({ name: "FPSCounter", rules: { groups: "Core" } })
+```
+
+Behavior:
+
+| Action         | Result                           |
+| -------------- | -------------------------------- |
+| Open Inventory | HUD + FPS stay                   |
+| Open Shop      | Inventory closes                 |
+| Open Pause     | ALL apps close except Core       |
+| Open HUD       | Never conflicts with SideButtons |
+| FPSCounter     | Always visible                   |
+
+---
+
+# 🧠 Using AppForge in UI Components
+
+```tsx
+function MenuUI(props: AppProps) {
+ return (
+  <frame Visible={props.appManager.getBind("Shop")}>
+   Shop UI…
+  </frame>
+ );
+}
+```
+
+---
+
+# ❗ Best Practices
+
+✔ Use `groups` for UI coexistence
+✔ Use `exclusive` for fullscreen menus
+✔ Use `blockedBy` for preventing conflicts
+✔ Use `blocks` for auto-closing logic
+✔ Use `Core` for never-closed apps
+✔ Use `layer` for future-proofing (not active yet)
+
+---
+
+# 🛠 Future Roadmap
+
+- [ ] layer / priority rendering
+
+---
+
+# ❤️ Contributing
+
+Feel free to submit PRs, suggestions, or feature requests.
+
+---
+
+# 📄 License
+
+MIT

package/out/container.d.ts

@@ -1,5 +1,5 @@
-import type AppManager from ".";
+import type AppForge from ".";
 export declare function AppContainer(props: AppProps & {
     name: AppNames[number];
-    manager: AppManager;
+    manager: AppForge;
 }): JSX.Element;

package/out/container.luau

@@ -8,13 +8,54 @@ local useBindingListener = _loners_pretty_react_hooks.useBindingListener
 local useSpring = _loners_pretty_react_hooks.useSpring
 local _react = TS.import(script, TS.getModule(script, "@rbxts", "react"))
 local React = _react
+local cloneElement = _react.cloneElement
+local useBinding = _react.useBinding
 local useState = _react.useState
 -- Types
+-- Components
+local AppRegistry = TS.import(script, script.Parent, "decorator").AppRegistry
+local function createBinding(name, manager)
+	local _name = name
+	local app = AppRegistry[_name]
+	if not app then
+		error(`App "{name}" not registered`)
+	end
+	local _condition = app.visible
+	if _condition == nil then
+		_condition = false
+	end
+	local binding = { useBinding(_condition) }
+	local _binds = manager.binds
+	local _name_1 = name
+	_binds[_name_1] = binding
+	return unpack(binding)
+end
+local function createInstance(props, name, manager)
+	local _name = name
+	local appClass = AppRegistry[_name]
+	if not appClass then
+		error(`App "{name}" not registered`)
+	end
+	local _loaded = manager.loaded
+	local _name_1 = name
+	if not (_loaded[_name_1] ~= nil) then
+		local instance = appClass.constructor.new(props, manager, name)
+		local element = cloneElement(instance:render(), {
+			key = "Main",
+		})
+		local _loaded_1 = manager.loaded
+		local _name_2 = name
+		_loaded_1[_name_2] = element
+	end
+	local _loaded_1 = manager.loaded
+	local _name_2 = name
+	return _loaded_1[_name_2]
+end
 local function AppContainer(props)
 	local _binding = props
 	local name = _binding.name
 	local manager = _binding.manager
-	local binding, _ = manager:createBinding(name)
+	local binding, _ = createBinding(name, manager)
 	local spring = useSpring(binding:map(function(v)
 		return if v then 0 else 1
 	end), {
@@ -22,7 +63,7 @@ local function AppContainer(props)
 		damping = 0.8,
 	})
 	local _isVisible, setisVisible = useState(binding:getValue())
-	local element = manager:createInstance(props, name)
+	local element = createInstance(props, name, manager)
 	if not element then
 		error(`Failed to create instance for app "{name}"`)
 	end

package/out/decorator.d.ts

@@ -1,9 +1,12 @@
 import React from "@rbxts/react";
 import type Types from "./types";
+import type AppForge from ".";
 export declare const AppRegistry: Map<string, Types.AppRegistry>;
-export declare function App(props: Types.AppRegistryProps): <T extends new (props: AppProps) => Args>(constructor: T) => T;
+export declare function App(props: Types.AppRegistryProps): <T extends new (props: AppProps, forge: AppForge, name: string) => Args>(constructor: T) => T;
 export declare abstract class Args {
+    readonly Forge: AppForge;
     readonly props: AppProps;
-    constructor(props: AppProps);
+    readonly name: AppNames[number];
+    constructor(props: AppProps, forge: AppForge, name: AppNames[number]);
     abstract render(): React.Element;
 }

package/out/decorator.luau

@@ -21,8 +21,10 @@ end
 local Args
 do
 	Args = {}
-	function Args:constructor(props)
+	function Args:constructor(props, forge, name)
 		self.props = props
+		self.Forge = forge
+		self.name = name
 	end
 end
 return {

package/out/helpers.d.ts

@@ -1,6 +1,6 @@
-import type AppManager from ".";
+import type AppForge from ".";
 export declare function Render({ props, manager, names, }: {
     props: AppProps;
-    manager: AppManager;
+    manager: AppForge;
     names?: AppNames[number] | AppNames[number][];
 }): JSX.Element | JSX.Element[];

package/out/index.d.ts

@@ -1,12 +1,9 @@
 import React from "@rbxts/react";
 import { Args, App } from "./decorator";
-export default class AppManager {
-    private binds;
-    private loaded;
+export default class AppForge {
+    binds: Map<string, [React.Binding<boolean>, (T: boolean) => void]>;
+    loaded: Map<string, React.Element<any, string | React.JSXElementConstructor<any>>>;
     private rulesManager;
-    private getAllNames;
-    createBinding(name: AppNames[number]): LuaTuple<[React.Binding<boolean>, (newValue: boolean) => void]>;
-    createInstance(props: AppProps, name: AppNames[number]): React.Element<any, string | React.JSXElementConstructor<any>>;
     getBind(name: AppNames[number]): React.Binding<boolean>;
     getState(name: AppNames[number]): boolean;
     set(name: AppNames[number], value: boolean): void;

package/out/init.luau

@@ -2,76 +2,33 @@
 local TS = _G[script]
 local exports = {}
 -- Packages
-local _react = TS.import(script, TS.getModule(script, "@rbxts", "react"))
-local React = _react
-local cloneElement = _react.cloneElement
-local useBinding = _react.useBinding
-local Object = TS.import(script, TS.getModule(script, "@rbxts", "object-utils"))
+local React = TS.import(script, TS.getModule(script, "@rbxts", "react"))
 -- Components
 local _decorator = TS.import(script, script, "decorator")
 local AppRegistry = _decorator.AppRegistry
 local Args = _decorator.Args
 local App = _decorator.App
 local AppContainer = TS.import(script, script, "container").AppContainer
+-- Classes
 local RulesManager = TS.import(script, script, "rules").default
-local AppManager
+local AppForge
 do
-	AppManager = setmetatable({}, {
+	AppForge = setmetatable({}, {
 		__tostring = function()
-			return "AppManager"
+			return "AppForge"
 		end,
 	})
-	AppManager.__index = AppManager
-	function AppManager.new(...)
-		local self = setmetatable({}, AppManager)
+	AppForge.__index = AppForge
+	function AppForge.new(...)
+		local self = setmetatable({}, AppForge)
 		return self:constructor(...) or self
 	end
-	function AppManager:constructor()
+	function AppForge:constructor()
 		self.binds = {}
 		self.loaded = {}
 		self.rulesManager = RulesManager.new(self)
 	end
-	function AppManager:getAllNames()
-		return Object.keys(AppRegistry)
-	end
-	function AppManager:createBinding(name)
-		local _name = name
-		local app = AppRegistry[_name]
-		if not app then
-			error(`App "{name}" not registered`)
-		end
-		local _condition = app.visible
-		if _condition == nil then
-			_condition = false
-		end
-		local binding = { useBinding(_condition) }
-		local _binds = self.binds
-		local _name_1 = name
-		_binds[_name_1] = binding
-		return unpack(binding)
-	end
-	function AppManager:createInstance(props, name)
-		local _name = name
-		local appClass = AppRegistry[_name]
-		if not appClass then
-			error(`App "{name}" not registered`)
-		end
-		local _loaded = self.loaded
-		local _name_1 = name
-		if not (_loaded[_name_1] ~= nil) then
-			local instance = appClass.constructor.new(props)
-			local element = cloneElement(instance:render(), {
-				key = "Main",
-			})
-			local _loaded_1 = self.loaded
-			local _name_2 = name
-			_loaded_1[_name_2] = element
-		end
-		local _loaded_1 = self.loaded
-		local _name_2 = name
-		return _loaded_1[_name_2]
-	end
-	function AppManager:getBind(name)
+	function AppForge:getBind(name)
 		local _binds = self.binds
 		local _name = name
 		if not (_binds[_name] ~= nil) then
@@ -81,10 +38,10 @@ do
 		local _name_1 = name
 		return _binds_1[_name_1][1]
 	end
-	function AppManager:getState(name)
+	function AppForge:getState(name)
 		return self:getBind(name):getValue()
 	end
-	function AppManager:set(name, value)
+	function AppForge:set(name, value)
 		if not self.rulesManager:applyRules(name, value) then
 			return nil
 		end
@@ -95,16 +52,16 @@ do
 		local setBinding = _binding[2]
 		setBinding(value)
 	end
-	function AppManager:open(name)
+	function AppForge:open(name)
 		self:set(name, true)
 	end
-	function AppManager:close(name)
+	function AppForge:close(name)
 		self:set(name, false)
 	end
-	function AppManager:toggle(name)
+	function AppForge:toggle(name)
 		self:set(name, not self:getState(name))
 	end
-	function AppManager:renderApp(props, name)
+	function AppForge:renderApp(props, name)
 		local _attributes = {
 			key = `{name}_Container`,
 			name = name,
@@ -115,7 +72,7 @@ do
 		end
 		return React.createElement(AppContainer, _attributes)
 	end
-	function AppManager:renderApps(props, names)
+	function AppForge:renderApps(props, names)
 		-- ▼ ReadonlyArray.map ▼
 		local _newValue = table.create(#names)
 		local _callback = function(n)
@@ -127,12 +84,22 @@ do
 		-- ▲ ReadonlyArray.map ▲
 		return _newValue
 	end
-	function AppManager:renderAll(props)
-		return self:renderApps(props, self:getAllNames())
+	function AppForge:renderAll(props)
+		local keys = {}
+		-- ▼ ReadonlyMap.forEach ▼
+		local _callback = function(_, name)
+			local _name = name
+			table.insert(keys, _name)
+		end
+		for _k, _v in AppRegistry do
+			_callback(_v, _k, AppRegistry)
+		end
+		-- ▲ ReadonlyMap.forEach ▲
+		return self:renderApps(props, keys)
 	end
 end
 exports.Render = TS.import(script, script, "helpers").Render
-exports.default = AppManager
+exports.default = AppForge
 exports.App = App
 exports.Args = Args
 return exports

package/out/types.d.ts

@@ -1,5 +1,6 @@
 // Types
 import type { Args } from "./decorator";
+import type AppForge from ".";
 
 declare namespace Types {
 	type AppRegistryProps = {
@@ -9,7 +10,7 @@ declare namespace Types {
 	};
 
 	type AppRegistry = {
-		constructor: new (props: AppProps) => Args;
+		constructor: new (props: AppProps, forge: AppForge, name: string) => Args;
 		visible?: boolean;
 		rules?: Rules.All;
 	};

package/package.json

@@ -1,59 +1,58 @@
 {
-    "name": "@rbxts/app-forge",
-    "version": "0.0.3",
-    "description": "An App Manager for react",
-    "main": "out/init.lua",
-    "packageManager": "bun@1.3.1",
-    "scripts": {
-        "build": "rbxtsc",
-        "dev": "rbxtsc -w --type game --rojo test.project.json",
-        "login": "bunx npm login --auth-type=legacy"
-
-    },
-    "keywords": [
-        "roblox-ts",
-        "react"
-    ],
-    "author": "loner1536",
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/Loner1536/AppForge"
-    },
-    "bugs": {
-        "url": "https://github.com/Loner1536/AppForge/issues"
-    },
-    "types": "out/index.d.ts",
-    "files": [
-        "out",
-        "!**/*.tsbuildinfo",
-        "!**/*.spec.lua",
-        "!**/*.spec.d.ts"
-    ],
-    "publishConfig": {
-        "access": "public"
-    },
-    "devDependencies": {
-        "@rbxts/compiler-types": "3.0.0-types.0",
-        "@rbxts/react": "17.3.0-alpha.1",
-        "@rbxts/react-roblox": "17.3.0-alpha.1",
-        "@rbxts/types": "^1.0.891",
-        "@typescript-eslint/eslint-plugin": "^8.46.4",
-        "@typescript-eslint/parser": "^8.46.4",
-        "roblox-ts": "3.0.0",
-        "typescript": "^5.9.3"
-    },
-    "dependencies": {
-        "@rbxts/charm": "^0.10.0",
-        "@rbxts/loners-pretty-react-hooks": "^0.0.3",
-        "@rbxts/react-charm": "^0.3.0",
-        "@rbxts/ripple": "^0.9.3",
-        "@rbxts/services": "^1.6.0",
-        "@rbxts/set-timeout": "^1.1.2"
-    },
-    "peerDependencies": {
-        "@rbxts/object-utils": "*",
-        "@rbxts/react-roblox": "*",
-        "@rbxts/react": "*"
-    }
+	"name": "@rbxts/app-forge",
+	"version": "0.0.6",
+	"description": "An App Manager for react",
+	"main": "out/init.lua",
+	"packageManager": "bun@1.3.1",
+	"scripts": {
+		"build": "rbxtsc",
+		"dev": "rbxtsc -w --type game --rojo test.project.json",
+		"login": "bunx npm login --auth-type=legacy"
+	},
+	"keywords": [
+		"roblox-ts",
+		"react"
+	],
+	"author": "loner1536",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/Loner1536/AppForge"
+	},
+	"bugs": {
+		"url": "https://github.com/Loner1536/AppForge/issues"
+	},
+	"types": "out/index.d.ts",
+	"files": [
+		"out",
+		"!**/*.tsbuildinfo",
+		"!**/*.spec.lua",
+		"!**/*.spec.d.ts"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.7",
+		"@rbxts/compiler-types": "3.0.0-types.0",
+		"@rbxts/react": "17.3.0-alpha.1",
+		"@rbxts/react-roblox": "17.3.0-alpha.1",
+		"@rbxts/types": "^1.0.891",
+		"@typescript-eslint/eslint-plugin": "^8.46.4",
+		"@typescript-eslint/parser": "^8.46.4",
+		"roblox-ts": "3.0.0",
+		"typescript": "^5.9.3"
+	},
+	"dependencies": {
+		"@rbxts/charm": "^0.10.0",
+		"@rbxts/loners-pretty-react-hooks": "^0.0.3",
+		"@rbxts/react-charm": "^0.3.0",
+		"@rbxts/ripple": "^0.9.3",
+		"@rbxts/services": "^1.6.0",
+		"@rbxts/set-timeout": "^1.1.2"
+	},
+	"peerDependencies": {
+		"@rbxts/react-roblox": "*",
+		"@rbxts/react": "*"
+	}
 }