wuira 0.2.3 → 0.2.4

package/CHANGELOG.md

@@ -7,6 +7,24 @@ with the release date and highlight breaking changes explicitly.
 
 ## Unreleased
 
+## 0.2.4 — 2026-10-15
+
+### Added
+
+- Observable keyed ForEach rendering. Stable keys retain native widgets and their
+  subscriptions across joins, leaves, reorder and metadata updates; only added or
+  removed records mount or dispose. Supports grouped layout and wrapping.
+- Native GroupRoster metadata with GUID identity, full-name/realm fallback, pet
+  ownership and raid subgroup membership. Retains the last readable roster if
+  native membership data becomes restricted.
+- Cell keys, event-driven GroupMembers subscriptions and shared UnitSource
+  retargeting. HP/Mana readers and event filters follow the existing unit reference.
+
+### Changed
+
+- Defer keyed structural updates and unit retargeting until combat ends, keeping
+  protected click targets aligned with displayed data.
+
 ## 0.2.3 — 2026-10-15
 
 ### Added

package/README.md

@@ -270,9 +270,10 @@ function SealButtons() {
 
 The render function receives the item and its zero-based index. Use `ForEach`
 inside a layout for multiple siblings; Cell still accepts at most one expanded
-child. Nested loops are flattened in order. `ForEach` creates no subscriptions:
+child. Nested loops are flattened in order. Array inputs create no subscriptions:
 recreate the view from `known.onChange` when needed, outside combat for protected
-trees. Each filtered rank remains a separate entry.
+trees. Each filtered rank remains a separate entry. Observable list sources also
+support keyed updates, as shown below under Group members.
 
 All visual cells accept `condition={boolean}` or `condition={() => boolean}`.
 This controls visibility and retains the layout slot. It combines with datasource
@@ -542,10 +543,45 @@ const raid = new RaidMembers();
 `GroupMembers` returns `["player"]` while solo, `player` plus `partyN` tokens
 in a party, and `raidN` tokens in a raid. `PartyMembers` is empty outside a
 party; `RaidMembers` is empty outside a raid. The player is included once.
-Offline members are retained. Each `.Value` access reads the current roster;
-there is no automatic subscription, polling, or UI rerender. Read again when
-handling `GROUP_ROSTER_UPDATE`. Tokens may refer to different members after
-roster changes and should not be used as persistent identities.
+Offline members are retained. Each `.Value` access reads the current roster.
+`onChange` subscribes to roster, pet, connection and name events without polling;
+unsubscribe or call `Dispose()` when done. Tokens may refer to different members
+after roster changes and should not be used as persistent identities.
+
+`GroupRoster` adds GUID-based keys, full-name/realm fallback, pet ownership and
+raid subgroup metadata. Pass it directly to `ForEach` to retain mounted cells and
+their resource subscriptions while the roster changes:
+
+```tsx
+import { UI, Wuira } from "wuira";
+import { ForEach, ProgressBar, type Element } from "wuira/ui";
+import { GroupRoster, HP, UnitSource } from "wuira/datasources";
+
+const roster = new GroupRoster("party", { pets: true, includeSelfWhenSolo: true });
+const units = new Map<Element, UnitSource>();
+const view = (
+    <ForEach items={roster} key={member => member.key}
+        direction="vertical" wrapAfter={5} gap={4} lineGap={8}
+        onUpdate={(view, member) => units.get(view)!.Retarget(member.unit)}
+        onDispose={view => { units.delete(view); }}>
+        {member => {
+            const unit = new UnitSource(member.unit);
+            const view = <ProgressBar width={160} height={24} source={new HP(unit)} />;
+            units.set(view, unit);
+            return view;
+        }}
+    </ForEach>
+);
+const frame = Wuira.Mount(view)!;
+// On teardown: Wuira.Unmount(frame); roster.Dispose();
+```
+
+Observable inputs expose `Value` and `onChange`, and require unique, public keys.
+Only new keys call the child factory; removed keys unmount and call `onDispose`.
+Use `onUpdate` to update retained views when their unit token or metadata changes.
+Structural changes wait until combat ends. The observable `ForEach` owns its
+layout and sizes its native host; mount it as a root or reserve an explicit slot
+in its parent layout. `groupBy` can arrange raid subgroups in separate columns.
 
 ### Player class and specialization
 
@@ -567,6 +603,9 @@ specs.RequestInspect();
 These sources accept real players only; NPCs produce no data or inspect request.
 The same `UnitSource` can be passed to `Buffs`, `Debuffs`, `HP`, and `Mana`.
 Its `Value` contains the current token and GUID, rather than a cached identity.
+`Retarget(token)` changes a shared reference outside combat; bound HP/Mana widgets
+refresh without replacing their sources. `onChange` observes these explicit token
+changes, not every change to the native unit's identity.
 `Is.PC` and `Is.Self` return `undefined` when their native result is secret.
 String unit tokens are still supported as a convenience shorthand.
 Own specialization data is read directly. Other players require an explicit,

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;
+}