@rbxts/app-forge 0.6.0 → 0.7.0

package/README.md

@@ -1,271 +1,456 @@
-# AppForge — React App & Window Manager for roblox-ts
+# AppForge
 
-AppForge is a UI/app orchestration system for React in Roblox, enabling:
+> ⚠️ **Documentation Notice**
+>
+> This README was written with the assistance of **AI tooling**.
+> I do not currently have the time to write a fully hand-crafted documentation site, so there may be typos, rough wording, or missing explanations.
+>
+> If you find an issue, inconsistency, or bug in the docs or API, please **@ me on Discord** in the **roblox-ts Discord**: `@loner71x`.
+>
+> Thank you for your patience ❤️
 
-✔ App registration
-✔ Visibility & state control
-✔ App grouping
-✔ Exclusive UI modes
-✔ Rule-based interactions
-✔ Priority & layering
-✔ React-friendly state bindings & animations
+> **An App Manager for Vide**
+
+AppForge is a **declarative UI application manager** built on top of [Vide](https://github.com/centau/vide) for **roblox-ts**. It provides a structured way to register, mount, show/hide, group, and coordinate UI "apps" using rules instead of ad‑hoc state wiring.
+
+If you’ve ever ended up with tangled UI state, duplicated visibility logic, or brittle parent/child UI dependencies — AppForge is meant to solve that without forcing you into complex patterns.
+
+---
+
+## ✨ Features
+
+* **App-based UI architecture**
+* **Centralized visibility state** per app
+* **Rule system** (parent/child, exclusive groups, z-index)
+* **Render groups** for selective mounting
+* **px scaling** built-in via `loners-pretty-vide-utils`
+* **Vide context integration**
+* **Story / sandbox rendering**
+* Fully typed with **roblox-ts**
 
 ---
 
-# 📦 Installation
+## 📦 Installation
 
 ```bash
-npm i @rbxts/app-forge
-# or
-bun i @rbxts/app-forge
+bun add @rbxts/app-forge
 ```
 
+Peer dependencies:
+
+```bash
+bun add @rbxts/vide @rbxts/loners-pretty-vide-utils
+```
+
+---
+
+## 🧠 Core Concepts
+
+### App
+
+An **App** is a self-contained UI unit:
+
+* owns its own visibility source
+* renders a Vide tree
+* can depend on other apps via rules
+
+Apps are registered using a decorator and rendered through `AppForge`.
+
+---
+
+### Forge
+
+`AppForge` is the runtime manager. It:
+
+* owns all app visibility sources
+* mounts and unmounts UI
+* enforces rules
+* exposes imperative helpers (`open`, `close`, `toggle`)
+
+You usually create **one Forge per UI root**.
+
+---
+
+### Rules
+
+Rules define **relationships between apps**, not layout.
+
+Currently supported:
+
+| Rule             | Description                            |
+| ---------------- | -------------------------------------- |
+| `parent`         | Child app closes when parent closes    |
+| `detach`         | Prevents automatic anchoring to parent |
+| `exclusiveGroup` | Only one app in the group may be open  |
+| `index`          | Sets ZIndex of the app container       |
+
+Rules are enforced automatically whenever visibility changes.
+
 ---
 
-# 🧩 Setup — REQUIRED
+### Render Groups
 
-### Create `global.d.ts`
+Render groups let you **selectively mount apps**.
+
+Example use cases:
+
+* Lobby UI vs In‑Game UI
+* HUD vs Menus
+* Feature‑flagged UI
+
+---
+
+## 🧩 Basic Usage
+
+### Creating a Forge
 
 ```ts
-declare global {
- type AppProps = {
-  player: Player;
- }
- export {};
-}
+const forge = new CreateVideForge();
 ```
 
-> App names are now autodetected via decorators — no need to define `AppNames` globally.
+> `CreateVideForge` owns its internal state. You **do not pass the forge into itself** — it is only provided to Apps at render-time.
 
 ---
 
-# 🚀 Initializing AppForge
+### Mounting (Game Runtime)
+
+AppForge is mounted once from application bootstrap code (commonly a Flamework controller).
 
 ```ts
-import { Workspace } from "@rbxts/services"
+const forge = new CreateVideForge();
+
+forge.mount(
+ () => (
+  <screengui
+   Name="App"
+   ZIndexBehavior="Sibling"
+   ResetOnSpawn={false}
+  />
+ ),
+ {
+  props,
+ },
+ Players.LocalPlayer.WaitForChild("PlayerGui"),
+);
+```
 
-import { createPortal, createRoot } from "@rbxts/react-roblox";
-import { Players, Workspace } from "@rbxts/services";
-import AppForge, { Render } from "@rbxts/app-forge";
-import React from "@rbxts/react";
+Notes:
 
-const forge = new AppForge();
-const root = createRoot(new Instance("Folder"));
+* `forge` is **implicitly available** to Apps
+* `props` are user-defined and become `this.props` inside Apps
+* visibility & rules are controlled entirely by the Forge
 
-const target = Workspace.CurrentCamera!
+---
+
+### Mounting (Game Runtime)
 
-const props = {
- player: Players.LocalPlayer!,
-} as const satisfies AppProps;
+AppForge is typically mounted from a **controller** (e.g. Flamework) and targets `PlayerGui`.
 
-root.render(
- createPortal(
-  <screengui ResetOnSpawn={false} ZIndexBehavior="Sibling">
-   <Render {...{ props, forge, root, target }} />
-  </screengui>,
-  Players.LocalPlayer!.WaitForChild("PlayerGui")!,
+```ts
+const forge = new CreateVideForge();
+
+forge.mount(
+ () => (
+  <screengui
+   Name="App"
+   ZIndexBehavior="Sibling"
+   ResetOnSpawn={false}
+  />
  ),
+ {
+  props,
+ },
+ Players.LocalPlayer.WaitForChild("PlayerGui"),
 );
 ```
 
-> `Render` will control all decorated apps.
+This:
+
+* creates a single root `ScreenGui`
+* mounts all rendered apps under it
+* keeps AppForge in control of visibility & rules
 
 ---
 
-# 🧱 Creating an App
+### Mounting
 
 ```ts
-import { App, Args } from "@rbxts/app-forge";
-import React from "@rbxts/react";
+forge.mount(
+ () => <screengui ResetOnSpawn={false} />,
+ {
+  props: {},
+ },
+ playerGui,
+);
+```
+
+---
+
+### Opening & Closing Apps
 
-@App({
- name: "SideButtons",
- visible: true,
+```ts
+forge.open("Inventory");
+forge.close("Inventory");
+forge.toggle("Inventory");
+```
+
+You can also access the reactive source directly:
+
+```ts
+const visible = forge.getSource("Inventory");
+```
+
+---
+
+## 🧱 Defining an App
+
+```ts
+import { VideApp, VideArgs } from "@rbxts/app-forge";
+import Vide from "@rbxts/vide";
+
+@VideApp({
+ name: "Inventory",
+ renderGroup: "Lobby",
+ visible: false,
+ rules: {
+  index: 2,
+ },
 })
-export default class SideButtons extends Args {
- public render() {
-  return <frame Size={UDim2.fromScale(1, 1)}>Side Buttons UI</frame>;
+export class Inventory extends VideArgs {
+ render() {
+  const { px } = this.props;
+
+  return (
+   <frame
+    BackgroundColor3={Color3.fromRGB(100, 100, 100)}
+    Size={() => UDim2.fromOffset(px(500), px(500))}
+   />
+  );
  }
 }
 ```
 
 ---
 
-# 📦 Props & `Args` Features
-
-Inside a decorated App:
+## 🔗 Parent / Child Apps
 
 ```ts
-this.forge   // AppForge instance
-this.name    // App Name
-this.props   // AppProps
-this.bind    // visible state bind
+@VideApp({
+ name: "InventoryInfo",
+ renderGroup: "Lobby",
+ rules: {
+  parent: "Inventory",
+ },
+})
+export class InventoryInfo extends VideArgs {
+ render() {
+  return <frame />;
+ }
+}
 ```
 
-Example:
+Behavior:
+
+* When `Inventory` closes → `InventoryInfo` closes
+* Child is **anchored** to parent unless `detach: true`
 
 ```ts
-const { px } = this.props;
-const scale2px = px.map((s) => s * 2);
+rules: {
+ parent: "Inventory",
+ detach: true,
+}
 ```
 
 ---
 
-# 🕹 App Manager API
+## 🚦 Exclusive Groups
 
 ```ts
-forge.toggle("Inventory");
-forge.set("Shop", true);
-forge.set("HUD", false);
-const shown = forge.getState("Pause");
-const bind = forge.getBind("Inventory");
+@VideApp({
+ name: "Settings",
+ rules: {
+  exclusiveGroup: "Menus",
+ },
+})
 ```
 
+Only one app in the same `exclusiveGroup` may be open at a time.
+
 ---
 
-# 📐 Using `getBind()` inside React
+## 🎭 Render Control
 
-```tsx
-return (
- <frame Visible={forge.getBind("Inventory")}>
-  Items…
- </frame>
-);
-```
+AppForge supports **multiple render selection modes**. You can render by:
+
+* a single app name
+* multiple app names
+* one or more render groups
+* combinations of `group + name(s)`
+
+All render options are passed via `VideRenderProps`.
 
 ---
 
-# ⌨️ Hotkey Toggle Example
+### Render a single app
 
 ```ts
-UserInputService.InputBegan.Connect((input) => {
- if (input.KeyCode === Enum.KeyCode.I)
-  forge.toggle("Inventory");
-});
+render: { name: "Inventory" }
 ```
 
 ---
 
-# ⚖️ APP RULES SYSTEM
+### Render multiple apps
 
-Rules control app visibility behavior.
-
-| Rule      | Effect                                  |
-| --------- | --------------------------------------- |
-| blockedBy | Prevents opening if another is open     |
-| blocks    | Closes another app when opened          |
-| exclusive | Closes ALL other apps except same group |
-| groups    | Non-conflicting coexistence grouping    |
-| Core      | Always allowed — never auto-closed      |
-| layer     | (Reserved – future rendering priority)  |
+```ts
+render: { names: ["Inventory", "InventoryInfo"] }
+```
 
 ---
 
-## `groups`
+### Render by group
 
 ```ts
-@App({ name: "HUD", rules: { groups: "HUD" } })
-@App({ name: "Crosshair", rules: { groups: "HUD" } })
+render: { group: "Lobby" }
 ```
 
-Both may open at the same time.
-
 ---
 
-## `Core`
+### Render by group + name
 
 ```ts
-@App({ name: "FPSCounter", rules: { groups: "Core" } })
+render: {
+ group: "Lobby",
+ name: "Inventory",
+}
 ```
 
-Never closed by rules.
+Only renders `Inventory` **if** it belongs to the `Lobby` group.
 
 ---
 
-# 🧪 Modern App Example (from your snippet)
+### Render by group + names
 
 ```ts
-@App({ name: "TestApp", visible: true, rules: { groups: "Core" } })
-export default class TestApp extends Args {
- public render() {
-  const { px } = this.props;
-
-  return (
-   <frame AnchorPoint={new Vector2(0.5, 1)}>
-    UI Stuff…
-   </frame>
-  );
- }
+render: {
+ group: "Lobby",
+ names: ["Inventory", "Settings"],
 }
 ```
 
+Only renders apps that:
+
+* are in the specified group(s)
+* and whose names match the provided list
+
 ---
 
-# 🧠 Using AppForge from Flamework
+## 🧪 Story / Sandbox Rendering
+
+AppForge provides `forge.story` for **isolated rendering**, commonly used with **UI Labs**.
 
 ```ts
-import AppForge, { Render } from "@rbxts/app-forge";
-
-@Controller()
-export default class AppController implements OnInit {
- onInit() {
-  const props = this.createProps(player);
-  const forge = new AppForge();
-  const root = createRoot(new Instance("Folder"));
-
-  root.render(
-   createPortal(
-    <screengui ResetOnSpawn={false}>
-     <Render {...{ props, forge, root, target: props.target }} />
-    </screengui>,
-    player.WaitForChild("PlayerGui"),
-   ),
-  );
- }
-}
+const forge = new CreateVideForge();
+
+return forge.story({
+ forge,
+ props,
+ config: {
+  px: {
+   target: storyProps.target,
+  },
+ },
+ render: { group: "Lobby" },
+});
 ```
 
+This is ideal for:
+
+* component stories
+* previews
+* controlled visibility via bindings
+
 ---
 
-# 🧠 Using with Storybook/Setup
+## 🧠 Context Access Inside Apps
 
-You can manually choose which apps render:
+App props are provided via Vide context.
+
+```ts
+import { Provider } from "@rbxts/vide";
+import { VideContexts } from "@rbxts/app-forge";
 
-```tsx
-<Render {...{ props, forge, target, name: "TestApp" }} />
+<Provider context={VideContexts.App} value={this.props}>
+ {() => <Child />}
+</Provider>
 ```
 
-or:
+Or via hook:
+
+````ts
+```ts
+import { useVideAppContext } from "@rbxts/app-forge";
+
+const app = useVideAppContext();
+````
 
-```tsx
-<Render {...{ props, forge, target, names: ["HUD", "Shop"] }} />
+---
+
+## 🧱 Architecture Overview
+
+```
+AppForge
+ ├─ AppRegistry (static)
+ ├─ Visibility Sources
+ ├─ Render Manager
+ ├─ Rule Engine
+ │   ├─ Parent Rule
+ │   └─ Exclusive Group Rule
+ └─ Vide Mount
 ```
 
 ---
 
-# ❗ Best Practices
+## ⚠️ Notes
 
-✔ Use `groups` for compatible UIs
-✔ Use `blockedBy` to avoid interruptions
-✔ Use `blocks` for mutual exclusion
-✔ Use `exclusive` for fullscreen control
-✔ Use `"Core"` for never-hidden persistent UI
-✔ Avoid manually instantiating apps
+* Apps are **singletons per Forge**
+* Rendering twice will warn if px is re‑initialized
+* Rules are enforced **reactively**
+* This package is currently **alpha** — APIs may change
 
 ---
 
-# 🛠 Future Roadmap
+## 🛣 Roadmap
 
-* [ ] UI layering & depth priority
+* [ ] Transition animations API
+* [ ] Async app loading
+* [ ] Better dev warnings
+* [ ] Debug inspector
 
 ---
 
-# ❤️ Contributing
+## ⚛️ React Support (Planned)
+
+AppForge is designed as a **renderer-agnostic App Manager**.
+
+Currently:
+
+* ✅ **Vide renderer** is production-ready
+* 🚧 **React renderer** exists but is **very early / experimental**
 
-PRs and suggestions welcome!
+React support is intentionally paused while the Vide API stabilizes. The author is still learning React, and decided to refocus on Vide first. React will be revisited once the core architecture is fully locked in.
+
+Public surface (subject to change):
+
+```ts
+import { ReactApp, ReactArgs, CreateReactForge } from "@rbxts/app-forge";
+```
+
+**Vide is the recommended and supported path today.**
 
 ---
 
-# 📄 License
+## 📜 License
 
 MIT
+
+---

package/out/global.d.ts

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

package/out/index.d.ts

@@ -1,19 +1,11 @@
-import Vide from "@rbxts/vide";
-import type Types from "./types";
-import { Args, App } from "./decorator";
-export default class AppForge {
-    sources: Map<string, Vide.Source<boolean>>;
-    loaded: Map<string, Vide.Node>;
-    private rulesManager;
-    getSource(name: AppNames[number]): Vide.Source<boolean>;
-    set(name: AppNames[number], value: Vide.Source<boolean> | boolean): void;
-    open(name: AppNames[number]): void;
-    close(name: AppNames[number]): void;
-    toggle(name: AppNames[number]): void;
-    renderApp(props: Types.NameProps & Types.MainProps): Vide.Node;
-    renderApps(props: Types.NameProps & Types.MainProps): Vide.Node[];
-    renderAll(props: Types.MainProps): Vide.Node[];
-}
-export { App, Args };
-export { Render } from "./helpers";
-export type { NameProps, MainProps, ClassProps } from "./types";
+export { App as ReactApp, Args as ReactArgs } from "./react/decorator";
+export { App as VideApp, Args as VideArgs } from "./vide/decorator";
+export { default as CreateReactForge } from "./react";
+export { default as CreateVideForge } from "./vide";
+export { Render as RenderReact } from "./react/helpers";
+export type { MainProps as VideProps, ClassProps as VideClassProps, RenderProps as VideRenderProps, } from "./vide/types";
+export type { MainProps as ReactProps, ClassProps as ReactClassProps, } from "./react/types";
+export { default as useReactAppContext } from "./react/hooks/useAppContext";
+export { default as ReactContexts } from "./react/context";
+export { default as useVideAppContext } from "./vide/hooks/useAppContext";
+export { default as VideContexts } from "./vide/context";