@rbxts/forge 0.0.5

package/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2024 Littensy
+
+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 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,146 @@
+# AppForge
+
+**⚠️ SOME OF THIS MIGHT BE OUTDATED! ⚠️**
+
+> ⚠️ **Documentation Notice**  
+> Written with AI assistance. Please report any issues in [GitHub Issues](https://github.com/Loner1536/AppForge/issues) or on Discord: `@loner71x`.
+
+**AppForge** is a **declarative UI application manager** for [Vide](https://github.com/centau/vide) in **roblox-ts**. It allows you to structure, mount, and control UI “apps” with centralized visibility, parent-child relationships, exclusive groups, and ZIndex rules — without tangled state.
+
+---
+
+## ✨ Features
+
+- **App-based UI architecture**: self-contained UI units  
+- **Centralized visibility** per app  
+- **Rules system**: parent/child, exclusive groups, ZIndex  
+- **Render groups** for selective mounting  
+- **Fully typed with roblox-ts**
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @rbxts/app-forge
+npm install @rbxts/vide
+
+Or using Bun:
+
+bun add @rbxts/app-forge
+bun add @rbxts/vide
+
+🧠 Core Concepts
+App
+
+An App is a self-contained UI unit:
+
+    Owns its visibility source
+
+    Renders a Vide tree
+
+    Can have rules: parent/child, exclusive groups, ZIndex
+
+Apps are defined using the @App decorator and must extend Args.
+Forge
+
+AppForge is the runtime manager:
+
+    Holds all visibility sources
+
+    Mounts/unmounts apps in the UI
+
+    Applies rules automatically
+
+    Exposes imperative helpers: open, close, toggle
+
+One Forge ONLY is VERY recommended.
+Rules
+    parent	Child app closes automatically when parent closes
+        parentGroup	Leave Empty if target Tree doesnt have one
+        attach	anchors child tree to parent
+
+    exclusiveGroup	Only one app in the group may be open
+    index	Sets ZIndex of the app tree
+
+Rules are reactively enforced when visibility changes.
+Render Groups
+
+Render groups let you mount selective apps:
+
+    Example: Lobby UI vs In-Game UI
+
+    Example: HUD vs Menus
+
+Apps can be rendered by group, name, or multiple names using the Forge’s internal rendering methods.
+🧩 Basic Usage
+Creating a Forge
+
+import { CreateForge } from "@rbxts/app-forge";
+
+const forge = new CreateForge();
+
+Mounting to the PlayerGui
+
+forge.mount(
+ <screengui
+  Name="AppRoot"
+  ZIndexBehavior="Sibling"
+  ResetOnSpawn={false}
+ />,
+ { props: {}, forge },
+ Players.LocalPlayer.WaitForChild("PlayerGui")
+);
+
+    ⚠️ Note: You pass the root node directly, not a function.
+
+Controlling Apps
+
+forge.open("Inventory");
+forge.close("Inventory");
+forge.toggle("Inventory");
+
+    open(name): Shows the app
+
+    close(name): Hides the app
+
+    toggle(name): Toggles visibility
+
+Defining an App
+
+import { App, Args } from "@rbxts/app-forge";
+
+@App({
+ name: "Inventory",
+ renderGroup: "Lobby",
+ visible: false,
+ rules: { zIndex: 2 },
+})
+export class Inventory extends Args {
+ render() {
+  const { px } = this.props; // px comes from the Forge
+
+  return (
+   <frame
+    BackgroundColor3={Color3.fromRGB(100, 100, 100)}
+    Size={() => UDim2.fromOffset(px(500), px(500))}
+   />
+  );
+ }
+}
+
+    @App registers the app with the Forge
+
+    px provides scaling helpers automatically
+
+    rules define relationships
+
+⚠️ Notes
+
+    Apps are singletons per Forge
+
+    API is alpha — may change
+
+📜 License
+
+MIT

package/out/appRegistry.d.ts

@@ -0,0 +1,21 @@
+import Vide from "@rbxts/vide";
+import type Types from "./types";
+export declare const AppRegistry: Map<string, Map<string, Types.AppRegistry.Static>>;
+export declare const AppSources: Map<string, Map<string, Vide.Source<boolean>>>;
+/**
+ * Registers a Vide App with AppForge.
+ *
+ * This runs at definition time and validates static configuration.
+ */
+export declare function App<N extends AppNames>(props: Types.AppRegistry.Props<N>): <T extends new (props: Types.Props.Main, name: AppNames, group?: AppGroups) => Args>(constructor: T) => T;
+/**
+ * Base class for all AppForge Apps.
+ */
+export declare abstract class Args {
+    readonly props: Types.Props.Class;
+    readonly source: Vide.Source<boolean>;
+    readonly group: AppGroups;
+    readonly name: AppNames;
+    constructor(props: Types.Props.Main, name: AppNames, group?: AppGroups);
+    abstract render(): Vide.Node;
+}

package/out/appRegistry.luau

@@ -0,0 +1,97 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+-- Packages
+-- Types
+-- Hooks
+local px = TS.import(script, script.Parent, "hooks", "usePx").px
+local AppRegistry = {}
+local AppSources = {}
+--[[
+	*
+	 * Registers a Vide App with AppForge.
+	 *
+	 * This runs at definition time and validates static configuration.
+	 
+]]
+local function App(props)
+	return function(constructor)
+		local _name = props.name
+		local _result = AppRegistry[_name]
+		if _result ~= nil then
+			local _condition = props.group
+			if not (_condition ~= "" and _condition) then
+				_condition = "None"
+			end
+			_result = _result[_condition] ~= nil
+		end
+		if _result then
+			local _exp = props.name
+			local _condition = props.group
+			if not (_condition ~= "" and _condition) then
+				_condition = "None"
+			end
+			error(`Duplicate registered App name "{_exp} in same Group name {_condition}". ` .. `App names must be globally unique.`, 2)
+		end
+		local _value = props.name
+		if not (_value ~= "" and _value) then
+			error("App registration failed: missing app name", 2)
+		end
+		local _name_1 = props.name
+		if not AppRegistry[_name_1] then
+			local _name_2 = props.name
+			AppRegistry[_name_2] = {}
+		end
+		local _name_2 = props.name
+		local _result_1 = AppRegistry[_name_2]
+		if _result_1 ~= nil then
+			local _condition = props.group
+			if not (_condition ~= "" and _condition) then
+				_condition = "None"
+			end
+			local _object = {
+				constructor = constructor,
+			}
+			local _left = "group"
+			local _condition_1 = props.group
+			if not (_condition_1 ~= "" and _condition_1) then
+				_condition_1 = "None"
+			end
+			_object[_left] = _condition_1
+			_object.visible = props.visible
+			_object.rules = props.rules
+			_result_1[_condition] = _object
+		end
+		return constructor
+	end
+end
+--[[
+	*
+	 * Base class for all AppForge Apps.
+	 
+]]
+local Args
+do
+	Args = {}
+	function Args:constructor(props, name, group)
+		local _binding = props
+		local forge = _binding.forge
+		local _condition = group
+		if not (_condition ~= "" and _condition) then
+			_condition = "None"
+		end
+		self.group = _condition
+		self.name = name
+		local _object = table.clone(props.props)
+		setmetatable(_object, nil)
+		_object.forge = forge
+		_object.px = px
+		self.props = _object
+		self.source = forge:getSource(name, group)
+	end
+end
+return {
+	App = App,
+	AppRegistry = AppRegistry,
+	AppSources = AppSources,
+	Args = Args,
+}

package/out/context.d.ts

@@ -0,0 +1,7 @@
+declare const Contexts: {
+    readonly App: import("@rbxts/vide").Context<{
+        forge: import("./forge").default;
+        px: typeof import("./hooks/usePx").px;
+    } | undefined>;
+};
+export default Contexts;

package/out/context.luau

@@ -0,0 +1,12 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+-- Packages
+local context = TS.import(script, TS.getModule(script, "@rbxts", "vide").src).context
+-- Types
+local Contexts = {
+	App = context(nil),
+}
+local default = Contexts
+return {
+	default = default,
+}

package/out/forge.d.ts

@@ -0,0 +1,22 @@
+import Vide from "@rbxts/vide";
+import type Types from "./types";
+import Renders from "./renders";
+export default class AppForge extends Renders {
+    constructor();
+    private createSource;
+    getSource(name: AppNames, group?: AppGroups): Vide.Source<boolean>;
+    bind(name: AppNames, group: AppGroups | undefined, value: Vide.Source<boolean>): void;
+    set(name: AppNames, group: AppGroups | undefined, value: boolean, rules?: boolean): void;
+    open(name: AppNames, group?: AppGroups, rules?: boolean): void;
+    close(name: AppNames, group?: AppGroups, rules?: boolean): void;
+    toggle(name: AppNames, group?: AppGroups, rules?: boolean): void;
+    story: ({ props, target, renders, config, }: {
+        props: AppProps;
+        target: GuiObject;
+        renders?: Types.Props.Render;
+        config?: Types.Props.Config;
+    }) => Frame;
+    render: ({ props }: {
+        props: Omit<Types.Props.Main, "forge">;
+    }) => Instance[];
+}

package/out/forge.luau

@@ -0,0 +1,209 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+-- Services
+local RunService = TS.import(script, TS.getModule(script, "@rbxts", "services")).RunService
+-- Packages
+local _vide = TS.import(script, TS.getModule(script, "@rbxts", "vide").src)
+local Vide = _vide
+local apply = _vide.apply
+local create = _vide.create
+local effect = _vide.effect
+local untrack = _vide.untrack
+-- Types
+-- Classes
+local Renders = TS.import(script, script.Parent, "renders").default
+-- Components
+local AppRegistry = TS.import(script, script.Parent, "appRegistry").AppRegistry
+-- Helpers
+local bindAppSource = TS.import(script, script.Parent, "helpers", "bindAppSource").default
+local getAppSource = TS.import(script, script.Parent, "helpers", "getAppSource").default
+local hasAppSource = TS.import(script, script.Parent, "helpers", "hasAppSource").default
+local setAppSource = TS.import(script, script.Parent, "helpers", "setAppSource").default
+local getAppEntry = TS.import(script, script.Parent, "helpers", "getAppEntry").default
+local AppForge
+do
+	local super = Renders
+	AppForge = setmetatable({}, {
+		__tostring = function()
+			return "AppForge"
+		end,
+		__index = super,
+	})
+	AppForge.__index = AppForge
+	function AppForge.new(...)
+		local self = setmetatable({}, AppForge)
+		return self:constructor(...) or self
+	end
+	function AppForge:constructor()
+		super.constructor(self)
+		self.story = function(_param)
+			local props = _param.props
+			local target = _param.target
+			local renders = _param.renders
+			local config = _param.config
+			local Container = create("Frame")({
+				Name = "Story Container",
+				BackgroundTransparency = 1,
+				AnchorPoint = Vector2.new(0.5, 0.5),
+				Position = UDim2.fromScale(0.5, 0.5),
+				Size = UDim2.fromScale(1, 1),
+			})
+			local _fn = apply(Container)
+			local _object = {}
+			local _left = 0
+			local _self = self
+			local _object_1 = {
+				props = props,
+				forge = self,
+				renders = renders,
+			}
+			local _left_1 = "config"
+			local _object_2 = {}
+			local _left_2 = "px"
+			local _object_3 = {
+				target = target,
+			}
+			local _left_3 = "minScale"
+			local _result = config
+			if _result ~= nil then
+				_result = _result.px.minScale
+			end
+			_object_3[_left_3] = _result
+			_object_2[_left_2] = _object_3
+			_object_1[_left_1] = _object_2
+			_object[_left] = _self:Initalize(_object_1)
+			_fn(_object)
+			return Container
+		end
+		self.render = function(_param)
+			local props = _param.props
+			local _self = self
+			local _object = table.clone(props)
+			setmetatable(_object, nil)
+			_object.forge = self
+			return _self:Initalize(_object)
+		end
+		-- ▼ ReadonlyMap.forEach ▼
+		local _callback = function(entryMap, name)
+			-- ▼ ReadonlyMap.forEach ▼
+			local _callback_1 = function(_, group)
+				self:createSource(name, group)
+			end
+			for _k, _v in entryMap do
+				_callback_1(_v, _k, entryMap)
+			end
+			-- ▲ ReadonlyMap.forEach ▲
+		end
+		for _k, _v in AppRegistry do
+			_callback(_v, _k, AppRegistry)
+		end
+		-- ▲ ReadonlyMap.forEach ▲
+	end
+	function AppForge:createSource(name, group)
+		if group == nil then
+			group = "None"
+		end
+		local entry = getAppEntry(name, group)
+		if not entry then
+			return nil
+		end
+		if hasAppSource(name, group) then
+			return nil
+		end
+		local _exp = name
+		local _exp_1 = group
+		local _condition = entry.visible
+		if _condition == nil then
+			_condition = false
+		end
+		setAppSource(_exp, _exp_1, _condition)
+	end
+	function AppForge:getSource(name, group)
+		if group == nil then
+			group = "None"
+		end
+		if not hasAppSource(name, group) then
+			self:createSource(name, group)
+		end
+		local src = getAppSource(name, group)
+		return src
+	end
+	function AppForge:bind(name, group, value)
+		if group == nil then
+			group = "None"
+		end
+		if not RunService:IsRunning() then
+			bindAppSource(name, group, value)
+			local count = 0
+			local _prev
+			effect(function()
+				count += 1
+				_prev = value()
+				untrack(function()
+					return self:checkRules(self, name, group)
+				end)
+				if Vide.strict and count == 2 then
+					count = 0
+				elseif not Vide.strict and count == 1 then
+					count = 0
+				end
+			end)
+		else
+			warn(".bind should ONLY be used for UI-Labs or something that displays UI WITHOUT the game running")
+		end
+	end
+	function AppForge:set(name, group, value, rules)
+		if group == nil then
+			group = "None"
+		end
+		if rules == nil then
+			rules = true
+		end
+		local src = getAppSource(name, group)
+		if not src then
+			return nil
+		end
+		local prev = src()
+		if prev == value then
+			return nil
+		end
+		src(value)
+		if rules then
+			self:checkRules(self, name, group)
+		end
+	end
+	function AppForge:open(name, group, rules)
+		if group == nil then
+			group = "None"
+		end
+		if rules == nil then
+			rules = true
+		end
+		self:set(name, group, true, rules)
+	end
+	function AppForge:close(name, group, rules)
+		if group == nil then
+			group = "None"
+		end
+		if rules == nil then
+			rules = true
+		end
+		self:set(name, group, false, rules)
+	end
+	function AppForge:toggle(name, group, rules)
+		if group == nil then
+			group = "None"
+		end
+		if rules == nil then
+			rules = true
+		end
+		local src = self:getSource(name, group)
+		if not src then
+			return nil
+		end
+		self:set(name, group, not src(), rules)
+	end
+end
+return {
+	default = AppForge,
+}

package/out/global.d.ts

@@ -0,0 +1,8 @@
+declare global {
+	// These will be overridden by the user
+	// They are only placeholders for your build
+	type AppGroups = string;
+	type AppNames = string;
+	type AppProps = {};
+}
+export {};

package/out/helpers/bindAppSource.d.ts

@@ -0,0 +1,2 @@
+import Vide from "@rbxts/vide";
+export default function bindAppSource(name: AppNames, group: AppGroups, value: Vide.Source<boolean>): void;

package/out/helpers/bindAppSource.luau

@@ -0,0 +1,22 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+-- Packages
+-- Components
+local AppSources = TS.import(script, script.Parent.Parent, "appRegistry").AppSources
+local function bindAppSource(name, group, value)
+	local _name = name
+	if not AppSources[_name] then
+		local _name_1 = name
+		AppSources[_name_1] = {}
+	end
+	local _name_1 = name
+	local _result = AppSources[_name_1]
+	if _result ~= nil then
+		local _group = group
+		local _value = value
+		_result[_group] = _value
+	end
+end
+return {
+	default = bindAppSource,
+}

package/out/helpers/getAppEntry.d.ts

@@ -0,0 +1 @@
+export default function getAppEntry(name: AppNames, group: AppGroups): import("../types").default.AppRegistry.Static | undefined;

package/out/helpers/getAppEntry.luau

@@ -0,0 +1,21 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+-- Components
+local AppRegistry = TS.import(script, script.Parent.Parent, "appRegistry").AppRegistry
+local function getAppEntry(name, group)
+	local _name = name
+	local entryMap = AppRegistry[_name]
+	local _entry = entryMap
+	if _entry ~= nil then
+		local _group = group
+		_entry = _entry[_group]
+	end
+	local entry = _entry
+	if not entry then
+		warn(`Failed to get entry for name {name} and group {group}`)
+	end
+	return entry
+end
+return {
+	default = getAppEntry,
+}

package/out/helpers/getAppSource.d.ts

@@ -0,0 +1 @@
+export default function getAppSource(name: AppNames, group: AppGroups): import("@rbxts/vide").Source<boolean> | undefined;

package/out/helpers/getAppSource.luau

@@ -0,0 +1,21 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+-- Components
+local AppSources = TS.import(script, script.Parent.Parent, "appRegistry").AppSources
+local function getAppSource(name, group)
+	local _name = name
+	local sourceMap = AppSources[_name]
+	local _source = sourceMap
+	if _source ~= nil then
+		local _group = group
+		_source = _source[_group]
+	end
+	local source = _source
+	if not source then
+		warn(`Failed to find source for name: {name} group: {group} \n {debug.traceback()}`)
+	end
+	return source
+end
+return {
+	default = getAppSource,
+}

package/out/helpers/hasAppSource.d.ts

@@ -0,0 +1 @@
+export default function hasAppSource(name: AppNames, group: AppGroups): boolean;

package/out/helpers/hasAppSource.luau

@@ -0,0 +1,24 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+-- Components
+local AppSources = TS.import(script, script.Parent.Parent, "appRegistry").AppSources
+local function hasAppSource(name, group)
+	local _name = name
+	local sourceMap = AppSources[_name]
+	if not sourceMap then
+		return false
+	end
+	local _source = sourceMap
+	if _source ~= nil then
+		local _group = group
+		_source = _source[_group]
+	end
+	local source = _source
+	if not source then
+		return false
+	end
+	return true
+end
+return {
+	default = hasAppSource,
+}

package/out/helpers/setAppSource.d.ts

@@ -0,0 +1 @@
+export default function setAppSource(name: AppNames, group: AppGroups, value: boolean): void;

package/out/helpers/setAppSource.luau

@@ -0,0 +1,34 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+-- Packages
+local source = TS.import(script, TS.getModule(script, "@rbxts", "vide").src).source
+-- Components
+local AppSources = TS.import(script, script.Parent.Parent, "appRegistry").AppSources
+local function setAppSource(name, group, value)
+	local _name = name
+	if not AppSources[_name] then
+		local _name_1 = name
+		AppSources[_name_1] = {}
+	end
+	local _name_1 = name
+	local _src = AppSources[_name_1]
+	if _src ~= nil then
+		local _group = group
+		_src = _src[_group]
+	end
+	local src = _src
+	if not src then
+		local newSource = source(value)
+		local _name_2 = name
+		local _result = AppSources[_name_2]
+		if _result ~= nil then
+			local _group = group
+			_result[_group] = newSource
+		end
+	else
+		src(false)
+	end
+end
+return {
+	default = setAppSource,
+}

package/out/hooks/useAppContext.d.ts

@@ -0,0 +1,5 @@
+declare const _default: () => {
+    forge: import("..").CreateForge;
+    px: typeof import("./usePx").px;
+};
+export default _default;