wuira 0.2.3 → 0.2.5

package/docs/icons.md

@@ -0,0 +1,28 @@
+# Forever icon catalog
+
+`Icons` contains native texture **FileDataIDs** from the same verified Forever build as the spell enums. Icon identity is independent of spell or item actions.
+
+```ts
+import { UI } from "wuira";
+import { Icons } from "wuira/icons";
+import { Icon } from "wuira/ui";
+
+const image = <Icon width={24} height={24} texture={Icons.BlessingOfFreedom_135968} />;
+```
+
+Every icon has an explicit ID-suffixed member. A readable short alias is generated only when that name maps to one icon. Multiple spells or items may share the same texture; they produce one catalog entry with searchable aliases.
+
+The snapshot combines SpellMisc spell/active icon fields with Item icon fields and ItemSparse names from the pinned client build. It covers every positive icon ID referenced by these tables, including unused records and entries without a readable name; it does not claim to list every texture or atlas in the game. No other client branch is merged into it. The names describe associated spells or items, rather than guessing asset filenames. Unnamed records receive a `Spell <id>` or `Item <id>` label.
+
+The generated enum is erased to numeric literals by TypeScriptToLua. Editor tools can read the packaged `data/icons/forever.json` to create a searchable catalog without constructing every icon in game. A selected texture is saved as a FileDataID, not a spell ID.
+
+Game data belongs to Blizzard Entertainment. Source URLs, row counts, build and SHA-256 hashes are recorded in the snapshot.
+
+## Update
+
+```sh
+npm run icons:update -- --build 1.60.1.70374
+npm run icons:generate
+```
+
+Use `--cached` to regenerate the snapshot from downloaded CSVs. Updating requires the build to match `data/spells/forever.json`. Normal consumers use the committed snapshot and do not download game data during a build.

package/docs/source-converters.md

@@ -0,0 +1,34 @@
+# Source converters
+
+`SourceConverter` transforms a readable source value. It consumes the input's change notifications, shares one upstream subscription across its observers, and does not create a timer or dispose the shared input. Sources without notifications remain available as checked one-time reads.
+
+```ts
+import { ClassSource, SourceConverter, CaseConverter, HP, MathConverter, Unit } from "wuira/datasources";
+
+const characterClass = new ClassSource(Unit.Player);
+const token = new SourceConverter(characterClass, info => info?.token);
+const color = new CaseConverter(token, [
+    { equals: "PALADIN", value: { r: 1, g: 0.5, b: 0.7, a: 1 } },
+    { equals: "MAGE", value: { r: 0.4, g: 0.8, b: 1, a: 1 } },
+], { r: 0.35, g: 0.4, b: 0.45, a: 1 });
+
+const hp = new HP(Unit.Player);
+const doubled = new MathConverter(hp, "2 * input");
+const stop = doubled.BindTo(value => console.log(value));
+// On removal:
+stop();
+doubled.Dispose();
+color.Dispose();
+token.Dispose();
+characterClass.Dispose();
+```
+
+`Value` and `Compute()` are checked reads. `TryCompute()` performs one checked read and returns `{ readable: false }` for restricted data, without invoking the callback. Converter chains use it to avoid repeated leaf reads. `onChange()` observes future readable output changes; `BindTo()` also applies the current readable value immediately. Scalar outputs with the same value do not emit again. `When()` filters emissions without changing the checked `Value` getter. Call `Dispose()` when the converter is no longer owned by a component.
+
+Cases compare strings, finite numbers and booleans with strict equality; `1` and `"1"` are different keys. Duplicate keys are rejected. Unmatched values return the supplied default, or `undefined` when none was provided. Case outputs can be colors, texture IDs, text or other data.
+
+Math expressions support `input`, finite numeric literals, parentheses, unary signs, `+`, `-`, `*`, `/`, `%`, and exponentiation (`^` or `**`). Exponents associate to the right; `-input^2` means `-(input^2)`. The bounded parser runs once at construction. It does not evaluate JavaScript or Lua, access globals, or call functions. Invalid syntax, division by zero and non-finite results throw errors. `MathConverter.Validate(expression)` checks syntax without reading the input.
+
+Restricted values, including nested secret fields, never reach a conversion callback. Restrictions are checked when values are consumed; combat alone does not mark a value secret. ClassSource subscriptions follow unit identity changes and relevant native events, and release those listeners when the last consumer unsubscribes.
+
+Converters produce data. They do not grant permission to change protected buttons or their actions during combat.

package/lib/datasources/DataSource.d.ts

@@ -1,3 +1,9 @@
+export type ReadResult<T> = {
+    readonly readable: true;
+    readonly value: T;
+} | {
+    readonly readable: false;
+};
 /** A value-producing source. Secrecy describes data, not native frame protection. */
 export declare abstract class DataSource<T> {
     private value;
@@ -8,6 +14,8 @@ export declare abstract class DataSource<T> {
     IsSecret(): boolean;
     get Value(): T;
     Compute<TResult>(compute: (value: T) => TResult): TResult;
+    /** One checked read, without exposing a restricted value or invoking its callback. */
+    TryCompute<TResult>(compute: (value: T) => TResult): ReadResult<TResult>;
     protected GetValue(): T;
     /** Filters native binding emissions; Value remains a checked, fresh snapshot. */
     When(condition: (value: T) => boolean): this;

package/lib/datasources/DataSource.lua

@@ -165,6 +165,13 @@ function DataSource.prototype.Compute(self, compute)
     self:AssertReadable(value)
     return compute(nil, value)
 end
+function DataSource.prototype.TryCompute(self, compute)
+    local value = self:GetValue()
+    return self:IsValueSecret(value) and ({readable = false}) or ({
+        readable = true,
+        value = compute(nil, value)
+    })
+end
 function DataSource.prototype.GetValue(self)
     return self.value
 end

package/lib/datasources/GroupMembers.d.ts

@@ -4,7 +4,13 @@ export type GroupScope = "auto" | "party" | "raid";
 export declare class GroupMembers extends DataSource<readonly string[]> {
     readonly scope: GroupScope;
     private restricted;
+    private readonly listeners;
+    private frame?;
     constructor(scope?: GroupScope);
+    /** Roster/connection events, with one listener frame while observed. No polling. */
+    onChange(listener: (units: readonly string[]) => void): () => void;
+    private StopListening;
+    Dispose(): void;
     protected HasSecretFields(): boolean;
     protected GetValue(): readonly string[];
 }

package/lib/datasources/GroupMembers.lua

@@ -32,6 +32,284 @@ local function __TS__ClassExtends(target, base)
     end
 end
 
+local __TS__Symbol, Symbol
+do
+    local symbolMetatable = {__tostring = function(self)
+        return ("Symbol(" .. (self.description or "")) .. ")"
+    end}
+    function __TS__Symbol(description)
+        return setmetatable({description = description}, symbolMetatable)
+    end
+    Symbol = {
+        asyncDispose = __TS__Symbol("Symbol.asyncDispose"),
+        dispose = __TS__Symbol("Symbol.dispose"),
+        iterator = __TS__Symbol("Symbol.iterator"),
+        hasInstance = __TS__Symbol("Symbol.hasInstance"),
+        species = __TS__Symbol("Symbol.species"),
+        toStringTag = __TS__Symbol("Symbol.toStringTag")
+    }
+end
+
+local __TS__Iterator
+do
+    local function iteratorGeneratorStep(self)
+        local co = self.____coroutine
+        local status, value = coroutine.resume(co)
+        if not status then
+            error(value, 0)
+        end
+        if coroutine.status(co) == "dead" then
+            return
+        end
+        return true, value
+    end
+    local function iteratorIteratorStep(self)
+        local result = self:next()
+        if result.done then
+            return
+        end
+        return true, result.value
+    end
+    local function iteratorStringStep(self, index)
+        index = index + 1
+        if index > #self then
+            return
+        end
+        return index, string.sub(self, index, index)
+    end
+    function __TS__Iterator(iterable)
+        if type(iterable) == "string" then
+            return iteratorStringStep, iterable, 0
+        elseif iterable.____coroutine ~= nil then
+            return iteratorGeneratorStep, iterable
+        elseif iterable[Symbol.iterator] then
+            local iterator = iterable[Symbol.iterator](iterable)
+            return iteratorIteratorStep, iterator
+        else
+            return ipairs(iterable)
+        end
+    end
+end
+
+local function __TS__New(target, ...)
+    local instance = setmetatable({}, target.prototype)
+    instance:____constructor(...)
+    return instance
+end
+
+local Set
+do
+    Set = __TS__Class()
+    Set.name = "Set"
+    function Set.prototype.____constructor(self, values)
+        self[Symbol.toStringTag] = "Set"
+        self.size = 0
+        self.nextKey = {}
+        self.previousKey = {}
+        if values == nil then
+            return
+        end
+        local iterable = values
+        if iterable[Symbol.iterator] then
+            local iterator = iterable[Symbol.iterator](iterable)
+            while true do
+                local result = iterator:next()
+                if result.done then
+                    break
+                end
+                self:add(result.value)
+            end
+        else
+            local array = values
+            for ____, value in ipairs(array) do
+                self:add(value)
+            end
+        end
+    end
+    function Set.prototype.add(self, value)
+        local isNewValue = not self:has(value)
+        if isNewValue then
+            self.size = self.size + 1
+        end
+        if self.firstKey == nil then
+            self.firstKey = value
+            self.lastKey = value
+        elseif isNewValue then
+            self.nextKey[self.lastKey] = value
+            self.previousKey[value] = self.lastKey
+            self.lastKey = value
+        end
+        return self
+    end
+    function Set.prototype.clear(self)
+        self.nextKey = {}
+        self.previousKey = {}
+        self.firstKey = nil
+        self.lastKey = nil
+        self.size = 0
+    end
+    function Set.prototype.delete(self, value)
+        local contains = self:has(value)
+        if contains then
+            self.size = self.size - 1
+            local next = self.nextKey[value]
+            local previous = self.previousKey[value]
+            if next ~= nil and previous ~= nil then
+                self.nextKey[previous] = next
+                self.previousKey[next] = previous
+            elseif next ~= nil then
+                self.firstKey = next
+                self.previousKey[next] = nil
+            elseif previous ~= nil then
+                self.lastKey = previous
+                self.nextKey[previous] = nil
+            else
+                self.firstKey = nil
+                self.lastKey = nil
+            end
+            self.nextKey[value] = nil
+            self.previousKey[value] = nil
+        end
+        return contains
+    end
+    function Set.prototype.forEach(self, callback)
+        for ____, key in __TS__Iterator(self:keys()) do
+            callback(nil, key, key, self)
+        end
+    end
+    function Set.prototype.has(self, value)
+        return self.nextKey[value] ~= nil or self.lastKey == value
+    end
+    Set.prototype[Symbol.iterator] = function(self)
+        return self:values()
+    end
+    function Set.prototype.entries(self)
+        local function getFirstKey()
+            return self.firstKey
+        end
+        local nextKey = self.nextKey
+        local key
+        local started = false
+        return {
+            [Symbol.iterator] = function(self)
+                return self
+            end,
+            next = function(self)
+                if not started then
+                    started = true
+                    key = getFirstKey(nil)
+                else
+                    key = nextKey[key]
+                end
+                return {done = not key, value = {key, key}}
+            end
+        }
+    end
+    function Set.prototype.keys(self)
+        local function getFirstKey()
+            return self.firstKey
+        end
+        local nextKey = self.nextKey
+        local key
+        local started = false
+        return {
+            [Symbol.iterator] = function(self)
+                return self
+            end,
+            next = function(self)
+                if not started then
+                    started = true
+                    key = getFirstKey(nil)
+                else
+                    key = nextKey[key]
+                end
+                return {done = not key, value = key}
+            end
+        }
+    end
+    function Set.prototype.values(self)
+        local function getFirstKey()
+            return self.firstKey
+        end
+        local nextKey = self.nextKey
+        local key
+        local started = false
+        return {
+            [Symbol.iterator] = function(self)
+                return self
+            end,
+            next = function(self)
+                if not started then
+                    started = true
+                    key = getFirstKey(nil)
+                else
+                    key = nextKey[key]
+                end
+                return {done = not key, value = key}
+            end
+        }
+    end
+    function Set.prototype.union(self, other)
+        local result = __TS__New(Set, self)
+        for ____, item in __TS__Iterator(other) do
+            result:add(item)
+        end
+        return result
+    end
+    function Set.prototype.intersection(self, other)
+        local result = __TS__New(Set)
+        for ____, item in __TS__Iterator(self) do
+            if other:has(item) then
+                result:add(item)
+            end
+        end
+        return result
+    end
+    function Set.prototype.difference(self, other)
+        local result = __TS__New(Set, self)
+        for ____, item in __TS__Iterator(other) do
+            result:delete(item)
+        end
+        return result
+    end
+    function Set.prototype.symmetricDifference(self, other)
+        local result = __TS__New(Set, self)
+        for ____, item in __TS__Iterator(other) do
+            if self:has(item) then
+                result:delete(item)
+            else
+                result:add(item)
+            end
+        end
+        return result
+    end
+    function Set.prototype.isSubsetOf(self, other)
+        for ____, item in __TS__Iterator(self) do
+            if not other:has(item) then
+                return false
+            end
+        end
+        return true
+    end
+    function Set.prototype.isSupersetOf(self, other)
+        for ____, item in __TS__Iterator(other) do
+            if not self:has(item) then
+                return false
+            end
+        end
+        return true
+    end
+    function Set.prototype.isDisjointFrom(self, other)
+        for ____, item in __TS__Iterator(self) do
+            if other:has(item) then
+                return false
+            end
+        end
+        return true
+    end
+    Set[Symbol.species] = Set
+end
+
 local function __TS__NumberIsFinite(value)
     return type(value) == "number" and value == value and value ~= math.huge and value ~= -math.huge
 end
@@ -55,6 +333,60 @@ function GroupMembers.prototype.____constructor(self, scope)
     DataSource.prototype.____constructor(self, {})
     self.scope = scope
     self.restricted = false
+    self.listeners = __TS__New(Set)
+end
+function GroupMembers.prototype.onChange(self, listener)
+    self.listeners:add(listener)
+    if self.listeners.size == 1 then
+        if self.frame == nil then
+            self.frame = CreateFrame("Frame", nil, UIParent)
+        end
+        for ____, event in ipairs({
+            "GROUP_ROSTER_UPDATE",
+            "UNIT_PET",
+            "UNIT_CONNECTION",
+            "UNIT_NAME_UPDATE",
+            "PLAYER_ENTERING_WORLD"
+        }) do
+            self.frame:RegisterEvent(event)
+        end
+        self.frame:SetScript(
+            "OnEvent",
+            function()
+                local units = self:GetValue()
+                if self.restricted then
+                    return
+                end
+                for ____, callback in __TS__Iterator(self.listeners) do
+                    callback(nil, units)
+                end
+            end
+        )
+    end
+    return function()
+        self.listeners:delete(listener)
+        if self.listeners.size == 0 then
+            self:StopListening()
+        end
+    end
+end
+function GroupMembers.prototype.StopListening(self)
+    local ____opt_0 = self.frame
+    if ____opt_0 ~= nil then
+        ____opt_0:UnregisterAllEvents()
+    end
+    local ____opt_2 = self.frame
+    if ____opt_2 ~= nil then
+        ____opt_2:SetScript("OnEvent", nil)
+    end
+    local ____opt_4 = self.frame
+    if ____opt_4 ~= nil then
+        ____opt_4:Hide()
+    end
+end
+function GroupMembers.prototype.Dispose(self)
+    self.listeners:clear()
+    self:StopListening()
 end
 function GroupMembers.prototype.HasSecretFields(self)
     return self.restricted

package/lib/datasources/GroupRoster.d.ts

@@ -0,0 +1,28 @@
+import { DataSource } from "./DataSource";
+import type { GroupScope } from "./GroupMembers";
+export interface GroupRosterMember {
+    readonly key: string;
+    readonly guid?: string;
+    readonly unit: string;
+    readonly pet: boolean;
+    readonly group: string;
+}
+export declare function getPetUnitToken(unit: string): string;
+/** Small snapshots describe identity/order only; keyed rendering owns widgets and unit sources. */
+export declare class GroupRoster extends DataSource<readonly GroupRosterMember[]> {
+    private readonly scope;
+    private readonly options;
+    private readonly roster;
+    private readonly knownNames;
+    private snapshot;
+    private restricted;
+    get Status(): "ready" | "restricted";
+    constructor(scope?: GroupScope, options?: {
+        pets?: boolean;
+        includeSelfWhenSolo?: boolean;
+    });
+    protected GetValue(): readonly GroupRosterMember[];
+    private Read;
+    onChange(listener: (members: readonly GroupRosterMember[]) => void): () => void;
+    Dispose(): void;
+}