wuira 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Uira contributors
+
+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

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# Uira
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The npm package and CLI command are named `wuira`. The framework API remains `UIra`. Future extension packages can use the `@wuira/` organization scope once that organization is registered.
+
+After publication:
+
+```sh
+npx wuira create MyAddon
+```
+
+A TypeScript and JSX UI framework for WoW Forever. TypeScriptToLua emits separate Lua files following the source directory structure. No Rollup or single-file Lua bundle is required.
+
+## CLI
+
+The CLI is not published to npm yet. Install dependencies in this repository and link the local command:
+
+```sh
+npm install
+npm link
+wuira create MyAddon
+cd MyAddon
+npm install
+wuira build
+```
+
+Without a global link, use `node /path/to/UIRa/cli/uira.cjs create MyAddon`. Generated projects also support `npm run build`.
+
+`create` refuses to overwrite an existing directory. It generates TypeScriptToLua configuration, addon metadata, a module loader, an MIT license, and this minimal `src/index.tsx`:
+
+```tsx
+import "./uira/console-polyfill";
+import { UI } from "./uira/ui/primitives/jsx";
+import { UIra } from "./uira/UIra";
+
+function App() {
+    console.log("MyAddon loaded");
+    return <></>;
+}
+
+UIra.Mount(App);
+```
+
+An empty fragment creates no native frame. Only empty fragments are currently supported; use a layout for multiple visual elements.
+
+`console.log/info/warn/error` use a global WoW console polyfill. Output goes to the local chat window, never to other players. The addon uses no Node.js runtime or stdin/stdout. `console.error` does not throw. Arguments are formatted with Lua `tostring`; objects are not deeply inspected. The CLI uses its own Node.js terminal console.
+
+## Build and distribution
+
+`wuira build` transpiles through `tsconfig.json`. It writes individual Lua modules, a loader, and a startup file to `dist/`, plus `<addonName>.toc` at the project root. The addon name lives in `uira.json`; Interface version and other metadata live in `addon.toc.in`. The default Interface version, 16001, targets the Forever playground.
+
+Copy the generated `.toc` file and `dist/` directory to `Interface/AddOns/<addonName>/`. No Node.js runtime or separate Uira addon is required in game. Module registries are isolated by addon name.
+
+This initial CLI copies framework sources into `src/uira/`. Updating the framework through a package is not supported yet. The existing repository's `src/index.tsx` playground remains intact.
+
+## Development
+
+```sh
+npm run build
+npm run check
+npm test
+```
+
+Cell is the basic visual box. FlowLayout and GridLayout arrange children. ProgressBar uses a native StatusBar, while data sources connect values to presentation. Behavior from other WoW versions must be verified against the Forever API before use.
+
+Licensed under MIT; see [LICENSE](LICENSE).
+
+## Releases
+
+Every pushed Git tag triggers `.github/workflows/publish.yml`. The workflow checks types, builds the framework, runs tests, and publishes the package to npm. Tags must match `package.json` version, optionally prefixed with `v` (for example `v0.1.0`). npm versions cannot be published twice.
+
+Before the first release, confirm that the package name in `package.json` is available or owned by your npm account. Configure the GitHub repository secret `NPM_TOKEN` with an npm granular access token authorized to publish this package and bypass 2FA for automation. Never commit the token. The repository also needs GitHub Actions enabled. No tag or package is published by local setup alone.

package/addon.toc.in

@@ -0,0 +1,4 @@
+## Interface: 16001
+## Title: Uira
+## Notes: Uira UI framework
+## Version: 0.1.0

package/cli/uira.cjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const root = path.resolve(__dirname, "..");
+
+function create(name, cwd = process.cwd()) {
+  if (!name || !/^[A-Za-z][A-Za-z0-9_-]*$/.test(name)) throw new Error("Use an addon name containing letters, numbers, underscores or hyphens, starting with a letter.");
+  const target = path.join(cwd, name);
+  if (fs.existsSync(target)) throw new Error(`Destination already exists: ${target}`);
+  fs.mkdirSync(target, { recursive: true });
+  const write = (file, value) => fs.writeFileSync(path.join(target, file), value);
+  fs.mkdirSync(path.join(target, "src"));
+  fs.cpSync(path.join(root, "src"), path.join(target, "src/uira"), {
+    recursive: true,
+    filter: source => !["index.tsx", "playground", "examples"].includes(path.basename(source)),
+  });
+  fs.cpSync(path.join(root, "tools"), path.join(target, "tools"), { recursive: true });
+  fs.mkdirSync(path.join(target, "cli"));
+  fs.copyFileSync(__filename, path.join(target, "cli/uira.cjs"));
+  const config = JSON.parse(fs.readFileSync(path.join(root, "tsconfig.json"), "utf8"));
+  write("tsconfig.json", JSON.stringify(config, null, 2) + "\n");
+  write("uira.json", JSON.stringify({ name }, null, 2) + "\n");
+  write("addon.toc.in", `## Interface: 16001\n## Title: ${name}\n## Notes: Built with Uira\n## Version: 0.1.0\n`);
+  write("src/index.tsx", `import "./uira/console-polyfill";\nimport { UI } from "./uira/ui/primitives/jsx";\nimport { UIra } from "./uira/UIra";\n\nfunction App() {\n    console.log("${name} loaded");\n    return <></>;\n}\n\nUIra.Mount(App);\n`);
+  const sourcePackage = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
+  const dependencies = { ...sourcePackage.devDependencies, ...sourcePackage.dependencies };
+  write("package.json", JSON.stringify({ name: name.toLowerCase(), version: "0.1.0", private: true,
+    license: "MIT", scripts: { build: "node cli/uira.cjs build", check: "tsc -p tsconfig.json --noEmit" },
+    devDependencies: { typescript: dependencies.typescript, "typescript-to-lua": dependencies["typescript-to-lua"] },
+  }, null, 2) + "\n");
+  fs.copyFileSync(path.join(root, "LICENSE"), path.join(target, "LICENSE"));
+  write(".gitignore", "node_modules/\ndist/\n*.toc\n");
+  write("README.md", `# ${name}\n\nInstall dependencies with \`npm install\`, then run \`wuira build\` or \`npm run build\`.\n\nThe entry is \`src/index.tsx\`. Its empty JSX creates no native frame; \`console.log\` writes only to the local WoW chat.\n\nCopy \`${name}.toc\` and \`dist/\` into \`Interface/AddOns/${name}/\`, then reload the game. Interface 16001 targets the current Forever playground; edit \`addon.toc.in\` for other clients.\n\nThis development scaffold includes Uira sources under \`src/uira\`; no separate in-game Uira addon is required.\n`);
+  return target;
+}
+
+function build(cwd = process.cwd()) {
+  if (!fs.existsSync(path.join(cwd, "tsconfig.json"))) throw new Error("Run wuira build inside an addon project.");
+  const compiler = require.resolve("typescript-to-lua/dist/tstl.js", { paths: [cwd, root] });
+  const result = spawnSync(process.execPath, [compiler, "-p", "tsconfig.json"], { cwd, stdio: "inherit" });
+  if (result.error) throw result.error;
+  if (result.status !== 0) throw new Error("Addon build failed.");
+}
+
+if (require.main === module) {
+  try {
+    const [command, name] = process.argv.slice(2);
+    if (command === "create") console.log(`Created ${create(name)}\nNext: cd ${name}, npm install, wuira build`);
+    else if (command === "build") build();
+    else if (!command || command === "--help") console.log("wuira create <addonName>\nwuira build");
+    else throw new Error(`Unknown command: ${command}`);
+  } catch (error) { console.error(error.message); process.exitCode = 1; }
+}
+module.exports = { create, build };

package/package.json

@@ -1,6 +1,26 @@
 {
   "name": "wuira",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "author": {
+    "name": "Kerim Cetinbas",
+    "email": "a.cetinbas@icloud.com"
+  },
+  "description": "TypeScript and JSX UI framework and addon CLI for WoW Forever",
+  "files": ["cli/", "src/", "tools/", "tsconfig.json", "addon.toc.in", "README.md", "LICENSE"],
+  "engines": { "node": ">=22" },
+  "license": "MIT",
+  "bin": { "wuira": "cli/uira.cjs" },
+  "scripts": {
+    "build": "tstl -p tsconfig.json",
+    "watch": "tstl -p tsconfig.json --watch",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test tests/*.test.cjs"
+  },
+  "devDependencies": {
+    "fengari-node-cli": "0.1.0"
+  },
+  "dependencies": {
+    "typescript": "6.0.2",
+    "typescript-to-lua": "1.37.1"
+  }
+}

package/src/Console.ts

@@ -0,0 +1,10 @@
+declare function print(this: void, message: string): void;
+
+/** Local client output only; never sends chat messages to other players. */
+export class Console {
+    private constructor() {}
+
+    public static Echo(message: string): void {
+        print(`|cff60d9c5[Uira]|r ${message}`);
+    }
+}

package/src/UIra.ts

@@ -0,0 +1,18 @@
+import type { Element } from "./ui/primitives/jsx";
+import type { Anchor } from "./types/Position";
+import { mount, unmount } from "./ui/mount";
+
+/** Public entry point for mounting JSX UI trees. */
+export class UIra {
+    private constructor() {}
+
+    public static Mount(frame: Element | (() => Element), anchor?: Anchor, parent?: UiraNativeFrame): UiraNativeFrame | undefined {
+        const view = typeof frame === "function" ? frame() : frame;
+        if (view.kind === "empty") return undefined;
+        return mount(view, parent, anchor);
+    }
+
+    public static Unmount(frame: UiraNativeFrame): void {
+        unmount(frame);
+    }
+}

package/src/console-polyfill.ts

@@ -0,0 +1,25 @@
+declare const _G: Record<string, unknown>;
+declare function print(this: void, message: string): void;
+declare function tostring(this: void, value: unknown): string;
+
+declare global {
+    const console: {
+        log(this: void, ...values: unknown[]): void;
+        info(this: void, ...values: unknown[]): void;
+        warn(this: void, ...values: unknown[]): void;
+        error(this: void, ...values: unknown[]): void;
+    };
+}
+
+function write(color: string, values: unknown[]): void {
+    print(`${color}${values.map(value => tostring(value)).join(" ")}|r`);
+}
+
+// Explicit side-effect import installs the WoW console; no Node runtime is used.
+_G.console = {
+    log: function(this: void, ...values: unknown[]) { write("|cffffffff", values); },
+    info: function(this: void, ...values: unknown[]) { write("|cff60d9c5", values); },
+    warn: function(this: void, ...values: unknown[]) { write("|cffffcc00", values); },
+    error: function(this: void, ...values: unknown[]) { write("|cffff5555", values); },
+};
+export {};

package/src/datasources/DataSource.ts

@@ -0,0 +1,42 @@
+/** A value-producing source. Secrecy describes data, not native frame protection. */
+export abstract class DataSource<T> {
+    protected constructor(private value: T, private secret: boolean = false) {}
+
+    /** Checked when consumed, rather than inferred from combat state. */
+    public IsSecret(): boolean {
+        return this.IsValueSecret(this.GetValue());
+    }
+
+    public get Value(): T {
+        const value = this.GetValue();
+        this.AssertReadable(value);
+        return value;
+    }
+
+    public Compute<TResult>(compute: (value: T) => TResult): TResult {
+        const value = this.GetValue();
+        this.AssertReadable(value);
+        return compute(value);
+    }
+
+    protected GetValue(): T { return this.value; }
+
+    private IsValueSecret(value: T): boolean {
+        return issecretvalue(value) || this.secret || this.HasSecretFields(value);
+    }
+
+    /** Replace the value and its explicit restriction together, clearing stale flags. */
+    protected SetValue(value: T, secret: boolean = false): void {
+        this.value = value;
+        this.secret = secret;
+    }
+
+    /** Aggregate sources override this to check known fields without comparing them. */
+    protected HasSecretFields(_value: T): boolean {
+        return false;
+    }
+
+    private AssertReadable(value: T): void {
+        if (this.IsValueSecret(value)) error("DataSource: secret data cannot be read or used in computations");
+    }
+}

package/src/datasources/NativeNumberSource.ts

@@ -0,0 +1,7 @@
+import { DataSource } from "./DataSource";
+
+/** Read-only API value; no cached assignment or game-state mutation. */
+export class NativeNumberSource extends DataSource<number> {
+    public constructor(private readonly read: () => number) { super(0); }
+    protected override GetValue(): number { return this.read(); }
+}

package/src/datasources/ProgressSource.ts

@@ -0,0 +1,46 @@
+import { DataSource } from "./DataSource";
+import { NativeNumberSource } from "./NativeNumberSource";
+
+export interface ProgressOverrides {
+    min?: number;
+    max?: number;
+    current?: number;
+}
+
+/** Shared contract for health, power, cooldowns, and other progress values. */
+export abstract class ProgressSource extends DataSource<number> {
+    public readonly Min: DataSource<number>;
+    public readonly Max: DataSource<number>;
+    public readonly Percent: DataSource<number>;
+
+    protected constructor(private readonly readers: {
+        current: () => number; min: () => number; max: () => number; percent: () => number;
+    }) {
+        super(0);
+        this.Min = new NativeNumberSource(readers.min);
+        this.Max = new NativeNumberSource(readers.max);
+        this.Percent = new NativeNumberSource(readers.percent);
+    }
+
+    protected override GetValue(): number { return this.readers.current(); }
+
+    public override IsSecret(): boolean {
+        return super.IsSecret() || this.Min.IsSecret() || this.Max.IsSecret() || this.Percent.IsSecret();
+    }
+
+    public BindTo(frame: UiraNativeStatusBar, options: ProgressOverrides = {}): void {
+        const refresh = () => {
+            // Do not compare or calculate opaque native values in the direct path.
+            const current = options.current !== undefined ? options.current : this.readers.current();
+            frame.SetMinMaxValues(
+                options.min !== undefined ? options.min : this.readers.min(),
+                options.max !== undefined ? options.max : this.readers.max(),
+            );
+            frame.SetValue(current);
+        };
+        this.Listen(frame, refresh);
+        refresh();
+    }
+
+    protected abstract Listen(frame: UiraNativeFrame, refresh: () => void): void;
+}

package/src/datasources/Resources.ts

@@ -0,0 +1,41 @@
+import { ProgressSource } from "./ProgressSource";
+
+export const Unit = { Player: "player" } as const;
+
+/** Direct API-to-widget binding; opaque values are never compared or calculated. */
+abstract class Resource extends ProgressSource {
+    protected constructor(
+        current: () => number,
+        maximum: () => number,
+        percent: () => number,
+        private readonly unitToken: string,
+        private readonly events: string[],
+    ) {
+        super({ current, min: () => 0, max: maximum, percent });
+    }
+
+    protected Listen(frame: UiraNativeFrame, refresh: () => void): void {
+        frame.SetScript("OnEvent", (_frame, event, unit) => {
+            if (event === "PLAYER_ENTERING_WORLD" || unit === this.unitToken) refresh();
+        });
+        frame.RegisterEvent("PLAYER_ENTERING_WORLD");
+        for (const event of this.events) frame.RegisterEvent(event);
+    }
+}
+
+export class HP extends Resource {
+    public constructor(public readonly unit: string) {
+        super(() => UnitHealth(unit), () => UnitHealthMax(unit),
+            () => UnitHealthPercent(unit, true, CurveConstants.ScaleTo100), unit, ["UNIT_HEALTH", "UNIT_MAXHEALTH"]);
+    }
+}
+
+/** Explicit mana (power type 0), even while the unit uses rage/energy. */
+export class Mana extends Resource {
+    public constructor(public readonly unit: string) {
+        super(() => UnitPower(unit, 0), () => UnitPowerMax(unit, 0),
+            () => UnitPowerPercent(unit, 0, true, CurveConstants.ScaleTo100), unit, ["UNIT_POWER_UPDATE", "UNIT_MAXPOWER", "UNIT_DISPLAYPOWER"]);
+    }
+}
+
+export const DataSources = { Resources: { HP, Mana } };

package/src/examples/ProgressBars.tsx

@@ -0,0 +1,24 @@
+import { UIra } from "../UIra";
+import { HP, Mana } from "../datasources/Resources";
+import { Cell } from "../ui/Cell";
+import { FlowLayout } from "../ui/FlowLayout";
+import { ProgressBar } from "../ui/ProgressBar";
+import { UI } from "../ui/primitives/jsx";
+
+function App() {
+
+    const mana = new Mana("player")
+    const hp = new HP("player")
+    return (
+        <FlowLayout width={160} height={80} >
+             <ProgressBar  source={mana} /> 
+             <ProgressBar foreground={{
+                texture: "blizzard",
+                color:  { r: 0.1, g: 0.1, b: 0.1 }
+             }}  source={hp} /> 
+        </FlowLayout>
+    );
+}
+
+UIra.Mount(App, "CENTER");
+

package/src/index.tsx

@@ -0,0 +1,3 @@
+import { RegisterPlayerFramePlayground } from "./playground/PlayerFrame";
+
+RegisterPlayerFramePlayground();

package/src/platform/forever.d.ts

@@ -0,0 +1,62 @@
+// Minimal API surface observed in locally installed Forever addons.
+// Global functions use dot calls; widget methods use Lua's colon calls.
+type UiraAnchor = import("../types/Position").Anchor;
+type UiraDrawLayer = "BACKGROUND" | "OVERLAY";
+interface UiraNativeTexture {
+    SetAllPoints(frame: UiraNativeFrame): void;
+    SetColorTexture(red: number, green: number, blue: number, alpha: number): void;
+    SetTexture(path: string): void;
+    SetVertexColor(red: number, green: number, blue: number, alpha: number): void;
+    SetBlendMode(mode: import("../types/Texture").BlendMode): void;
+    SetHorizTile(enabled: boolean): void;
+    SetVertTile(enabled: boolean): void;
+    SetTexCoord(left: number, right: number, top: number, bottom: number): void;
+    SetSize(width: number, height: number): void;
+    SetPoint(point: UiraAnchor, relativeTo: UiraNativeFrame, relativePoint: UiraAnchor, x: number, y: number): void;
+    SetParent(parent: UiraNativeFrame): void;
+    ClearAllPoints(): void;
+    Show(): void;
+    Hide(): void;
+}
+
+interface UiraNativeFrame {
+    EnableMouse(enabled: boolean): void;
+    RegisterEvent(event: string): void;
+    UnregisterAllEvents(): void;
+    SetScript(script: "OnEvent", handler: ((this: void, frame: UiraNativeFrame, event: string, unit?: string) => void) | undefined): void;
+    GetWidth(): number;
+    GetHeight(): number;
+    SetSize(width: number, height: number): void;
+    SetPoint(point: UiraAnchor, relativeTo: UiraNativeFrame, relativePoint: UiraAnchor, x: number, y: number): void;
+    CreateTexture(name: undefined, layer: UiraDrawLayer): UiraNativeTexture;
+    Show(): void;
+    Hide(): void;
+    SetParent(parent: UiraNativeFrame): void;
+    ClearAllPoints(): void;
+    SetAllPoints(frame: UiraNativeFrame): void;
+    SetBackdrop(backdrop: { edgeFile: string; edgeSize: number }): void;
+    SetBackdropBorderColor(red: number, green: number, blue: number, alpha: number): void;
+}
+
+declare const UIParent: UiraNativeFrame;
+interface UiraNativeStatusBar extends UiraNativeFrame {
+    GetStatusBarTexture(): UiraNativeTexture;
+    SetMinMaxValues(min: number, max: number): void;
+    SetValue(value: number): void;
+    SetStatusBarTexture(path: string): void;
+    SetStatusBarColor(red: number, green: number, blue: number, alpha: number): void;
+    SetOrientation(orientation: "HORIZONTAL" | "VERTICAL"): void;
+    SetReverseFill(reverse: boolean): void;
+}
+
+declare function CreateFrame(this: void, kind: "StatusBar", name: undefined, parent: UiraNativeFrame): UiraNativeStatusBar;
+declare function CreateFrame(this: void, kind: "Frame", name: undefined, parent: UiraNativeFrame, template?: "BackdropTemplate"): UiraNativeFrame;
+declare function error(this: void, message: string): never;
+declare function issecretvalue(this: void, value: unknown): boolean;
+declare function UnitHealth(this: void, unit: string): number;
+declare function UnitHealthMax(this: void, unit: string): number;
+declare function UnitPower(this: void, unit: string, powerType: number): number;
+declare function UnitPowerMax(this: void, unit: string, powerType: number): number;
+declare const CurveConstants: { readonly ScaleTo100: unknown };
+declare function UnitHealthPercent(this: void, unit: string, predicted: boolean, curve: unknown): number;
+declare function UnitPowerPercent(this: void, unit: string, powerType: number, predicted: boolean, curve: unknown): number;