wuira 0.1.0 → 0.1.2

package/package.json

@@ -1,17 +1,67 @@
 {
   "name": "wuira",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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" },
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.lua"
+    },
+    "./ui": {
+      "types": "./lib/ui/index.d.ts",
+      "default": "./lib/ui/index.lua"
+    },
+    "./datasources": {
+      "types": "./lib/datasources/index.d.ts",
+      "default": "./lib/datasources/index.lua"
+    },
+    "./console-polyfill": {
+      "types": "./lib/console-polyfill.d.ts",
+      "default": "./lib/console-polyfill.lua"
+    },
+    "./config/tsconfig.json": "./config/tsconfig.json",
+    "./tools/wow-modules.mjs": "./tools/wow-modules.mjs",
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "ui": [
+        "lib/ui/index.d.ts"
+      ],
+      "datasources": [
+        "lib/datasources/index.d.ts"
+      ],
+      "console-polyfill": [
+        "lib/console-polyfill.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "cli/",
+    "lib/",
+    "tools/",
+    "config/",
+    "templates/",
+    "tsconfig.json",
+    "tsconfig.lib.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.13"
+  },
   "license": "MIT",
-  "bin": { "wuira": "cli/uira.cjs" },
+  "bin": {
+    "wuira": "cli/wuira.mjs"
+  },
   "scripts": {
-    "build": "tstl -p tsconfig.json",
+    "build": "node tools/build-library.mjs",
+    "prepack": "npm run build",
     "watch": "tstl -p tsconfig.json --watch",
     "check": "tsc -p tsconfig.json --noEmit",
     "test": "node --test tests/*.test.cjs"

package/templates/addon/README.md

@@ -0,0 +1,13 @@
+# {{addonName}}
+
+Run `npm install`, then `npm run build` (or `npx wuira build`).
+
+Edit `src/index.tsx` to build your UI. The initial empty fragment creates no native frame and logs only to the local WoW chat.
+
+Copy the contents of `dist/` to `Interface/AddOns/{{addonName}}/`. The output includes its own TOC and all required Lua modules.
+
+Import components from `wuira/ui`, data sources from `wuira/datasources`, and `UI` and `wuira` from `wuira`. Generated declarations and compiled Lua come from the npm package; no framework sources are copied into your project.
+
+Set `outDir` in `wuira.config.mjs` to a relative or absolute path to build directly into your game's addon folder. Node.js and this configuration file are development tools only; they are not needed by the game.
+
+Interface 16001 targets Forever. Edit `addon.toc.in` to change addon metadata.

package/templates/addon/addon.toc.in

@@ -0,0 +1,4 @@
+## Interface: 16001
+## Title: {{addonName}}
+## Notes: Built with wuira
+## Version: 0.1.0

package/templates/addon/gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+*.toc

package/templates/addon/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "{{packageName}}",
+  "version": "0.1.0",
+  "private": true,
+  "license": "MIT",
+  "scripts": {
+    "build": "wuira build",
+    "check": "tsc -p tsconfig.json --noEmit"
+  },
+  "devDependencies": { "wuira": "{{frameworkVersion}}" }
+}

package/templates/addon/src/index.tsx

@@ -0,0 +1,7 @@
+import { wuira } from "wuira";
+
+function App() {
+    console.log("{{addonName}} loaded");
+}
+
+wuira.Mount(App);

package/templates/addon/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "wuira/config/tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx"]
+}

package/templates/addon/wuira.config.mjs

@@ -0,0 +1,4 @@
+export default {
+    name: "{{addonName}}",
+    outDir: "./dist",
+};

package/tools/build-library.mjs

@@ -0,0 +1,15 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const root = path.resolve(import.meta.dirname, "..");
+const result = spawnSync(process.execPath, [require.resolve("typescript-to-lua/dist/tstl.js"), "-p", "tsconfig.lib.json"], { cwd: root, stdio: "inherit" });
+if (result.status !== 0) process.exit(result.status || 1);
+fs.mkdirSync(path.join(root, "lib/platform"), { recursive: true });
+fs.copyFileSync(path.join(root, "src/platform/forever.d.ts"), path.join(root, "lib/platform/forever.d.ts"));
+for (const file of ["index.d.ts", "ui/index.d.ts", "datasources/index.d.ts"]) {
+  const target = path.join(root, "lib", file);
+  const reference = file === "index.d.ts" ? "./platform/forever.d.ts" : "../platform/forever.d.ts";
+  fs.writeFileSync(target, `/// <reference path="${reference}" />\n` + fs.readFileSync(target, "utf8"));
+}

package/tools/module-loader.lua

@@ -2,9 +2,9 @@
 local factories, cache, loading = {}, {}, {}
 local function requireModule(name)
     if cache[name] ~= nil then return cache[name] end
-    if loading[name] then error("UIRa: circular import: " .. name) end
+    if loading[name] then error("wuira: circular import: " .. name) end
     local factory = factories[name]
-    if not factory then error("UIRa: missing module: " .. name) end
+    if not factory then error("wuira: missing module: " .. name) end
     loading[name] = true
     local ok, result = pcall(factory, requireModule)
     loading[name] = nil
@@ -13,4 +13,4 @@ local function requireModule(name)
     cache[name] = result
     return result
 end
-__UIRaModules = { factories = factories, require = requireModule }
+__wuiraModules = { factories = factories, require = requireModule }

package/tools/{wow-modules.cjs → wow-modules.mjs}

@@ -1,15 +1,29 @@
-const path = require("node:path");
-const fs = require("node:fs");
+import path from "node:path";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
 
 // WoW loads files through the TOC, rather than a filesystem-based require.
 // Register each emitted module first; execute the entry only after registration.
-module.exports = {
+export default {
+  moduleResolution(dependency, requiringFile) {
+    if (requiringFile.endsWith(".lua")) return;
+    if (dependency === "wuira" || dependency.startsWith("wuira/")) {
+      const packageFile = require.resolve("wuira/package.json", { paths: [path.dirname(requiringFile)] });
+      const subpath = dependency === "wuira" ? "index" : dependency.slice(6);
+      const base = path.join(path.dirname(packageFile), "lib", subpath);
+      for (const file of [base + ".lua", path.join(base, "index.lua")]) {
+        if (fs.existsSync(file)) return file;
+      }
+    }
+  },
   beforeEmit(program, options, host, files) {
     const root = path.dirname(options.configFilePath);
-    const configPath = path.join(root, "uira.json");
-    const addon = fs.existsSync(configPath) ? JSON.parse(fs.readFileSync(configPath, "utf8")) : { name: "UIRa" };
+    const configPath = path.join(root, "wuira.json");
+    const addon = fs.existsSync(configPath) ? JSON.parse(fs.readFileSync(configPath, "utf8")) : { name: "wuira" };
+    if (process.env.WUIRA_ADDON_NAME) addon.name = process.env.WUIRA_ADDON_NAME;
     if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(addon.name)) throw new Error("Invalid addon name");
-    const registry = "__UIRaModules_" + addon.name.replace(/-/g, "_");
+    const registry = "__wuiraModules_" + addon.name.replace(/-/g, "_");
     const out = path.resolve(root, options.outDir);
     const moduleFiles = files.filter(file => file.outputPath.endsWith(".lua"));
     for (const file of moduleFiles) {
@@ -27,14 +41,16 @@ module.exports = {
       if (!modules.includes(relative)) modules.push(relative);
     }
     modules.sort();
-    const loader = fs.readFileSync(path.join(__dirname, "module-loader.lua"), "utf8");
-    const actualRegistry = addon.name === "UIRa" && !fs.existsSync(configPath) ? "__UIRaModules" : registry;
+    const loader = fs.readFileSync(path.join(import.meta.dirname, "module-loader.lua"), "utf8");
+    const actualRegistry = addon.name === "wuira" && !fs.existsSync(configPath) ? "__wuiraModules" : registry;
     if (actualRegistry !== registry) for (const file of moduleFiles) file.code = file.code.replace(registry, actualRegistry);
-    files.push({ outputPath: path.join(out, "__loader.lua"), code: loader.replace(/__UIRaModules/g, actualRegistry) });
+    files.push({ outputPath: path.join(out, "__loader.lua"), code: loader.replace(/__wuiraModules/g, actualRegistry) });
+    // Framework builds register modules only; addon projects own their startup and TOC.
+    if (!fs.existsSync(path.join(root, "addon.toc.in"))) return;
     files.push({ outputPath: path.join(out, "__start.lua"), code: `${actualRegistry}.require("index")\n` });
     const toc = fs.readFileSync(path.join(root, "addon.toc.in"), "utf8");
     const entries = ["__loader.lua", ...modules, "__start.lua"]
-      .map(file => path.relative(root, path.join(out, file)).replace(/\//g, "\\"));
-    files.push({ outputPath: path.join(root, `${addon.name}.toc`), code: toc + "\n" + entries.join("\n") + "\n" });
+      .map(file => (process.env.WUIRA_STANDALONE ? file : path.relative(root, path.join(out, file))).replace(/\//g, "\\"));
+    files.push({ outputPath: path.join(process.env.WUIRA_STANDALONE ? out : root, `${addon.name}.toc`), code: toc + "\n" + entries.join("\n") + "\n" });
   },
 };

package/tsconfig.json

@@ -16,7 +16,7 @@
     "luaTarget": "universal",
     "luaLibImport": "inline",
     "noImplicitGlobalVariables": true,
-    "luaPlugins": [{ "name": "./tools/wow-modules.cjs" }]
+    "luaPlugins": [{ "name": "./tools/wow-modules.mjs" }]
   },
   "include": ["src/**/*.ts", "src/**/*.tsx"]
 }

package/tsconfig.lib.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "lib",
+    "declaration": true
+  },
+  "tstl": { "luaPlugins": [] }
+}

package/addon.toc.in

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

package/cli/uira.cjs

@@ -1,55 +0,0 @@
-#!/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/src/Console.ts

@@ -1,10 +0,0 @@
-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

@@ -1,18 +0,0 @@
-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

@@ -1,25 +0,0 @@
-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

@@ -1,42 +0,0 @@
-/** 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

@@ -1,7 +0,0 @@
-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

@@ -1,46 +0,0 @@
-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

@@ -1,41 +0,0 @@
-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

@@ -1,24 +0,0 @@
-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

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