@rbxts/app-forge 0.7.1 → 0.7.2-alpha.2

package/out/vide/debug/init.luau

@@ -0,0 +1,8 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local Debugger = TS.import(script, script, "debugger").default
+local Logger = TS.import(script, script, "logger").default
+return {
+	Debugger = Debugger,
+	Logger = Logger,
+}

package/out/vide/debug/logger.d.ts

@@ -0,0 +1,5 @@
+export default class Logger {
+    private readonly scope;
+    constructor(scope: string);
+    log(level: "DEBUG" | "PERF" | "INFO" | "WARN" | "ERROR", message: string, data?: unknown, traceback?: string): void;
+}

package/out/vide/debug/logger.luau

@@ -0,0 +1,37 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+-- debug/logger.ts
+local RunService = TS.import(script, TS.getModule(script, "@rbxts", "services")).RunService
+local Logger
+do
+	Logger = setmetatable({}, {
+		__tostring = function()
+			return "Logger"
+		end,
+	})
+	Logger.__index = Logger
+	function Logger.new(...)
+		local self = setmetatable({}, Logger)
+		return self:constructor(...) or self
+	end
+	function Logger:constructor(scope)
+		self.scope = scope
+	end
+	function Logger:log(level, message, data, traceback)
+		if not RunService:IsStudio() then
+			return nil
+		end
+		local prefix = `[{self.scope}][{level}]`
+		if data ~= nil then
+			print(prefix, message, data)
+		else
+			print(prefix, message)
+		end
+		if traceback ~= "" and traceback then
+			print(traceback)
+		end
+	end
+end
+return {
+	default = Logger,
+}

package/out/vide/decorator.d.ts

@@ -2,7 +2,15 @@ import Vide from "@rbxts/vide";
 import type Types from "./types";
 import type AppForge from ".";
 export declare const AppRegistry: Map<string, Types.AppRegistry.Static>;
+/**
+ * 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) => Args>(constructor: T) => T;
+/**
+ * Base class for all AppForge Apps.
+ */
 export declare abstract class Args {
     readonly forge: AppForge;
     readonly props: Types.Props.Class;

package/out/vide/decorator.luau

@@ -1,15 +1,40 @@
 -- Compiled with roblox-ts v3.0.0
 local TS = _G[script]
 -- Packages
-local px = TS.import(script, TS.getModule(script, "@rbxts", "loners-pretty-vide-utils").out).px
 -- Types
+-- Hooks
+local px = TS.import(script, script.Parent, "hooks", "usePx").px
+-- Debug
+local Logger = TS.import(script, script.Parent, "debug", "logger").default
+local logger = Logger.new("AppRegistry")
 local AppRegistry = {}
+--[[
+	*
+	 * 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
 		if AppRegistry[_name] ~= nil then
-			error(`Duplicate registered App name "{props.name}"`)
+			logger:log("ERROR", "Duplicate App name detected", {
+				name = props.name,
+			})
+			error(`Duplicate registered App name "{props.name}". ` .. `App names must be globally unique.`, 2)
 		end
+		local _value = props.name
+		if not (_value ~= "" and _value) then
+			logger:log("ERROR", "Attempted to register App without a name", props)
+			error("App registration failed: missing app name", 2)
+		end
+		logger:log("DEBUG", "Registering App", {
+			name = props.name,
+			renderGroup = props.renderGroup,
+			visible = props.visible,
+			rules = props.rules,
+		})
 		local _name_1 = props.name
 		local _arg1 = {
 			constructor = constructor,
@@ -21,6 +46,11 @@ local function App(props)
 		return constructor
 	end
 end
+--[[
+	*
+	 * Base class for all AppForge Apps.
+	 
+]]
 local Args
 do
 	Args = {}
@@ -28,13 +58,20 @@ do
 		local _binding = props
 		local forge = _binding.forge
 		self.forge = forge
+		self.name = name
 		local _object = table.clone(props.props)
 		setmetatable(_object, nil)
 		_object.px = px
 		_object.forge = forge
 		self.props = _object
-		self.name = name
-		self.source = forge:getSource(name)
+		local src = forge:getSource(name)
+		if not src then
+			logger:log("ERROR", "Missing visibility source for App", {
+				name = name,
+			})
+			error(`Failed to retrieve visibility source for app "{name}"`, 2)
+		end
+		self.source = src
 	end
 end
 return {

package/out/vide/hooks/useAppContext.d.ts

@@ -1,5 +1,5 @@
 declare const _default: () => {
     forge: import("..").default;
-    px: typeof import("@rbxts/loners-pretty-vide-utils").px;
+    px: typeof import("./usePx").px;
 };
 export default _default;

package/out/vide/hooks/useAppContext.luau

@@ -2,10 +2,14 @@
 local TS = _G[script]
 -- Components
 local Contexts = TS.import(script, script.Parent.Parent, "context").default
+-- Debug
+local Logger = TS.import(script, script.Parent.Parent, "debug", "logger").default
+local logger = Logger.new("useAppContext")
 local default = function()
 	local context = Contexts.App()
 	if not context then
-		error(`Failed to retrieve App Props for Vide {debug.traceback()}`)
+		logger:log("ERROR", "Failed to retrieve App context")
+		error(`Failed to retrieve App Props for Vide\n{debug.traceback()}`, 2)
 	end
 	return context
 end

package/out/vide/hooks/useEventListener.d.ts

@@ -0,0 +1,17 @@
+type EventLike<T extends Callback = Callback> = {
+    Connect(callback: T): ConnectionLike;
+} | {
+    connect(callback: T): ConnectionLike;
+} | {
+    subscribe(callback: T): ConnectionLike;
+};
+type ConnectionLike = {
+    Disconnect(): void;
+} | {
+    disconnect(): void;
+} | (() => void);
+/**
+ * Subscribes to an event-like object and auto-cleans up.
+ */
+export declare function useEventListener<T extends EventLike>(event: T, listener: T extends EventLike<infer U> ? U : never): ReturnType<T>;
+export {};

package/out/vide/hooks/useEventListener.luau

@@ -0,0 +1,61 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local cleanup = TS.import(script, TS.getModule(script, "@rbxts", "vide").src).cleanup
+-- Debug
+local Logger = TS.import(script, script.Parent.Parent, "debug", "logger").default
+local logger = Logger.new("useEventListener")
+local connect = function(event, callback)
+	local _event = event
+	if typeof(_event) == "RBXScriptSignal" then
+		local connection
+		connection = event:Connect(function(...)
+			local args = { ... }
+			if connection.Connected then
+				return callback(unpack(args))
+			end
+		end)
+		return connection
+	elseif event.Connect ~= nil then
+		return event:Connect(callback)
+	elseif event.connect ~= nil then
+		return event:connect(callback)
+	elseif event.subscribe ~= nil then
+		return event:subscribe(callback)
+	end
+	logger:log("ERROR", "Unsupported event-like object", event)
+	error("Event-like object does not have a supported connect method.", 2)
+end
+local disconnect = function(connection)
+	local _connection = connection
+	if type(_connection) == "function" then
+		connection()
+	else
+		local _connection_1 = connection
+		local _condition = typeof(_connection_1) == "RBXScriptConnection"
+		if not _condition then
+			_condition = connection.Disconnect ~= nil
+		end
+		if _condition then
+			connection:Disconnect()
+		elseif connection.disconnect ~= nil then
+			connection:disconnect()
+		else
+			logger:log("WARN", "Unsupported connection-like object during cleanup", connection)
+		end
+	end
+end
+--[[
+	*
+	 * Subscribes to an event-like object and auto-cleans up.
+	 
+]]
+local function useEventListener(event, listener)
+	local connection = connect(event, listener)
+	cleanup(function()
+		return disconnect(connection)
+	end)
+	return connection
+end
+return {
+	useEventListener = useEventListener,
+}

package/out/vide/hooks/usePx.d.ts

@@ -0,0 +1,11 @@
+export declare const px: ((value: number) => number) & {
+    scale: (value: number) => number;
+    even: (value: number) => number;
+    floor: (value: number) => number;
+    ceil: (value: number) => number;
+};
+/**
+ * Initializes global px scaling.
+ * Must be called exactly once.
+ */
+export declare function usePx(target?: GuiObject | Camera, baseResolution?: Vector2, minScale?: number): void;

package/out/vide/hooks/usePx.luau

@@ -0,0 +1,103 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+-- Services
+local Workspace = TS.import(script, TS.getModule(script, "@rbxts", "services")).Workspace
+-- Packages
+local source = TS.import(script, TS.getModule(script, "@rbxts", "vide").src).source
+-- Helpers
+local useEventListener = TS.import(script, script.Parent, "useEventListener").useEventListener
+-- Debug
+local Logger = TS.import(script, script.Parent.Parent, "debug", "logger").default
+local logger = Logger.new("usePx")
+--* Default reference resolution for px calculations 
+local BASE_RESOLUTION = source(Vector2.new(1920, 1080))
+--* Minimum allowed scale to prevent unreadable UI 
+local MIN_SCALE = source(0.5)
+--* 0 = width-based, 1 = height-based 
+local DOMINANT_AXIS = 0.5
+local TARGET = source(Workspace.CurrentCamera)
+local SCALE = source(1)
+local INITIALIZED = false
+local function callable(callback, object)
+	return setmetatable(object, {
+		__call = function(_, ...)
+			local args = { ... }
+			return callback(unpack(args))
+		end,
+	})
+end
+local px = callable(function(value)
+	return math.round(value * SCALE())
+end, {
+	scale = function(value)
+		return value * SCALE()
+	end,
+	even = function(value)
+		return math.round(value * SCALE() * 0.5) * 2
+	end,
+	floor = function(value)
+		return math.floor(value * SCALE())
+	end,
+	ceil = function(value)
+		return math.ceil(value * SCALE())
+	end,
+})
+local function calculateScale()
+	local target = TARGET()
+	if not target then
+		return nil
+	end
+	local size = if target:IsA("Camera") then target.ViewportSize elseif target:IsA("GuiObject") then target.AbsoluteSize else nil
+	if not size then
+		return nil
+	end
+	local res = BASE_RESOLUTION()
+	if res.X <= 0 or res.Y <= 0 then
+		return nil
+	end
+	local min = MIN_SCALE()
+	local width = math.log(size.X / res.X, 2)
+	local height = math.log(size.Y / res.Y, 2)
+	local centered = width + (height - width) * DOMINANT_AXIS
+	local scale = 2 ^ centered
+	SCALE(math.max(scale, min))
+end
+--[[
+	*
+	 * Initializes global px scaling.
+	 * Must be called exactly once.
+	 
+]]
+local function usePx(target, baseResolution, minScale)
+	if INITIALIZED then
+		logger:log("WARN", "usePx() called more than once")
+		return nil
+	end
+	INITIALIZED = true
+	logger:log("DEBUG", "Initializing px scaling", {
+		target = target,
+		baseResolution = baseResolution,
+		minScale = minScale,
+	})
+	if baseResolution then
+		BASE_RESOLUTION(baseResolution)
+	end
+	if minScale ~= nil then
+		MIN_SCALE(minScale)
+	end
+	if target then
+		TARGET(target)
+	end
+	local resolvedTarget = TARGET()
+	if not resolvedTarget then
+		logger:log("WARN", "usePx(): no valid target to observe")
+		return nil
+	end
+	local signal = if resolvedTarget:IsA("Camera") then resolvedTarget:GetPropertyChangedSignal("ViewportSize") else resolvedTarget:GetPropertyChangedSignal("AbsoluteSize")
+	useEventListener(signal, calculateScale)
+	calculateScale()
+end
+return {
+	usePx = usePx,
+	px = px,
+}

package/out/vide/index.d.ts

@@ -1,6 +1,7 @@
 import Vide from "@rbxts/vide";
 import Renders from "./classes/renders";
 import Types from "./types";
+import { Logger, Debugger } from "./debug";
 type Destructor = () => void;
 type Loaded = {
     container: Vide.Node;
@@ -8,17 +9,19 @@ type Loaded = {
     anchor?: Vide.Node;
 };
 export default class AppForge extends Renders {
+    readonly logger: Logger;
+    readonly debug: Debugger;
     protected sources: Map<string, Vide.Source<boolean>>;
     protected loaded: Map<string, Loaded>;
     protected innerMount?: Destructor;
     protected __px: boolean;
     constructor();
-    protected createSource(name: AppNames): typeof Vide.source | undefined;
+    protected createSource(name: AppNames): void;
+    getSource(name: AppNames): Vide.Source<boolean>;
     isLoaded(name: AppNames): boolean;
     bind(name: AppNames, value: Vide.Source<boolean>): void;
     anchor(name: AppNames, anchorName: AppNames, props: Types.Props.Main): void;
     index(name: AppNames, index: number): void;
-    getSource(name: AppNames): Vide.Source<boolean>;
     set(name: AppNames, value: boolean, rules?: boolean): void;
     open(name: AppNames, rules?: boolean): void;
     close(name: AppNames, rules?: boolean): void;

package/out/vide/init.luau

@@ -14,6 +14,10 @@ local untrack = _vide.untrack
 local Renders = TS.import(script, script, "classes", "renders").default
 -- Helpers
 local AppRegistry = TS.import(script, script, "decorator").AppRegistry
+-- Debug
+local _debug = TS.import(script, script, "debug")
+local Logger = _debug.Logger
+local Debugger = _debug.Debugger
 local AppForge
 do
 	local super = Renders
@@ -30,6 +34,10 @@ do
 	end
 	function AppForge:constructor()
 		super.constructor(self)
+		self.logger = Logger.new("AppForge")
+		self.debug = Debugger.new(function(level, msg, data, trace)
+			return self.logger:log(level, msg, data, trace)
+		end)
 		self.sources = {}
 		self.loaded = {}
 		self.__px = false
@@ -46,22 +54,48 @@ do
 		local _name = name
 		local app = AppRegistry[_name]
 		if not app then
-			error(`App "{name}" not registered`)
+			self.logger:log("ERROR", "App not registered while creating source", {
+				name = name,
+			})
+			return nil
 		end
 		local _sources = self.sources
 		local _name_1 = name
 		if _sources[_name_1] ~= nil then
 			return nil
 		end
-		local _sources_1 = self.sources
+		local _debug_1 = self.debug
 		local _exp = name
+		local _object = {}
+		local _left = "default"
 		local _condition = app.visible
 		if _condition == nil then
 			_condition = false
 		end
-		local _arg1 = source(_condition)
-		_sources_1[_exp] = _arg1
-		return source
+		_object[_left] = _condition
+		_debug_1:logTag("state", _exp, "Creating visibility source", _object)
+		local _sources_1 = self.sources
+		local _exp_1 = name
+		local _condition_1 = app.visible
+		if _condition_1 == nil then
+			_condition_1 = false
+		end
+		local _arg1 = source(_condition_1)
+		_sources_1[_exp_1] = _arg1
+	end
+	function AppForge:getSource(name)
+		local _sources = self.sources
+		local _name = name
+		if not (_sources[_name] ~= nil) then
+			self:createSource(name)
+		end
+		local _sources_1 = self.sources
+		local _name_1 = name
+		local src = _sources_1[_name_1]
+		if not src then
+			error(`AppForge invariant broken: missing visibility source for {name}`, 2)
+		end
+		return src
 	end
 	function AppForge:isLoaded(name)
 		local _loaded = self.loaded
@@ -70,6 +104,7 @@ do
 	end
 	function AppForge:bind(name, value)
 		if not RunService:IsRunning() then
+			self.debug:logTag("state", name, "Binding external visibility source")
 			local _sources = self.sources
 			local _name = name
 			local _value = value
@@ -81,17 +116,26 @@ do
 				end)
 			end)
 		else
-			warn("forge.bind is used for studio when game isnt running")
+			self.logger:log("WARN", "forge.bind called while game is running", {
+				name = name,
+			})
 		end
 	end
 	function AppForge:anchor(name, anchorName, props)
 		if name == anchorName then
-			error(`Tried to anchor an App to itself`)
+			self.logger:log("ERROR", "Attempted to anchor app to itself", {
+				name = name,
+			})
+			return nil
 		end
 		local _anchorName = anchorName
 		local anchorApp = AppRegistry[_anchorName]
 		if not anchorApp then
-			error(`Failed to get class for {anchorName} from AppRegistry for anchor`)
+			self.logger:log("ERROR", "Anchor parent not registered", {
+				child = name,
+				parent = anchorName,
+			})
+			return nil
 		end
 		local _loaded = self.loaded
 		local _name = name
@@ -101,11 +145,17 @@ do
 		end
 		local render = _render
 		if not render then
-			error(`Failed to get {name} from this.loaded for anchor to {anchorName}`)
+			self.debug:logTag("rules", name, "Anchor skipped (child not rendered yet)", {
+				parent = anchorName,
+			})
+			return nil
 		end
+		self.debug:logTag("rules", name, "Anchoring to parent", {
+			parent = anchorName,
+		})
 		local anchor = anchorApp.constructor.new(props, anchorName):render()
-		for _, children in anchor:GetDescendants() do
-			children:Destroy()
+		for _, child in anchor:GetDescendants() do
+			child:Destroy()
 		end
 		apply(anchor)({
 			Name = "Anchor",
@@ -116,7 +166,7 @@ do
 		local _name_1 = name
 		local prev = _loaded_1[_name_1]
 		if not prev then
-			error(`Failed to retreive prev loaded data for {name}`)
+			error(`AppForge invariant broken: missing loaded app for {name}`, 2)
 		end
 		apply(prev.container)({
 			[0] = anchor,
@@ -133,22 +183,19 @@ do
 		local _name = name
 		local loaded = _loaded[_name]
 		if not loaded then
-			error(`Failed to retreive loaded data for app: {name}`)
+			self.logger:log("WARN", "ZIndex skipped (app not loaded)", {
+				name = name,
+				index = index,
+			})
+			return nil
 		end
+		self.debug:logTag("rules", name, "Applying ZIndex", {
+			index = index,
+		})
 		apply(loaded.container)({
 			ZIndex = index,
 		})
 	end
-	function AppForge:getSource(name)
-		local _sources = self.sources
-		local _name = name
-		if not (_sources[_name] ~= nil) then
-			self:createSource(name)
-		end
-		local _sources_1 = self.sources
-		local _name_1 = name
-		return _sources_1[_name_1]
-	end
 	function AppForge:set(name, value, rules)
 		if rules == nil then
 			rules = true
@@ -162,10 +209,21 @@ do
 			local _name_1 = name
 			src = _sources_1[_name_1]
 		end
-		if src() == value then
+		if not src then
+			self.logger:log("ERROR", "Failed to set visibility (missing source)", {
+				name = name,
+			})
+			return nil
+		end
+		local prev = src()
+		if prev == value then
 			return nil
 		end
 		src(value)
+		self.debug:logTag("state", name, "Visibility changed", {
+			from = prev,
+			to = value,
+		})
 		if rules then
 			self:checkRules(name)
 		end
@@ -189,6 +247,7 @@ do
 		self:set(name, not self:getSource(name)(), rules)
 	end
 	function AppForge:story(props)
+		self.debug:logTag("lifecycle", "story", "Creating story mount")
 		local Container = create("Frame")({
 			Name = "Story Container",
 			BackgroundTransparency = 1,
@@ -202,6 +261,7 @@ do
 		return Container
 	end
 	function AppForge:mount(callback, props, target)
+		self.debug:logTag("lifecycle", "mount", "Mounting AppForge")
 		local Container = callback()
 		self.innerMount = mount(function()
 			apply(Container)({
@@ -212,6 +272,7 @@ do
 		return self.innerMount
 	end
 	function AppForge:unMount()
+		self.debug:logTag("lifecycle", "unmount", "Unmounting AppForge")
 		local _result = self.innerMount
 		if _result ~= nil then
 			_result()

package/out/vide/types.d.ts

@@ -26,7 +26,7 @@ declare namespace Types {
 
 		type Class = AppProps & {
 			forge: AppForge;
-			px: typeof import("@rbxts/loners-pretty-vide-utils").px;
+			px: typeof import("./hooks/usePx").px;
 		};
 	}
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rbxts/app-forge",
-	"version": "0.7.1",
+	"version": "0.7.2-alpha.2",
 	"description": "An App Manager for Vide",
 	"main": "out/init.lua",
 	"types": "out/index.d.ts",
@@ -38,11 +38,17 @@
 		"@rbxts/set-timeout": "^1.1.2"
 	},
 	"peerDependencies": {
-		"@rbxts/loners-pretty-react-hooks": "^0.2.9",
-		"@rbxts/loners-pretty-vide-utils": "^0.1.7",
 		"@rbxts/react": "^17.3.7-ts.1",
 		"@rbxts/vide": "^0.5.7"
 	},
+	"peerDependenciesMeta": {
+		"@rbxts/react": {
+			"optional": true
+		},
+		"@rbxts/vide": {
+			"optional": true
+		}
+	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.3.7",
 		"@rbxts/compiler-types": "3.0.0-types.0",