wuira 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -9,6 +9,56 @@ with the release date and highlight breaking changes explicitly.
 
 No changes yet.
 
+## 0.1.5 — 2026-10-14
+
+### Added
+
+- Event-driven `.When(value => boolean)` source conditions. Inactive bindings
+  hide their visual and skip writes; secret inputs never reach callbacks.
+  Repeated conditions combine with AND, and fresh `.Value` reads remain unchanged.
+- Opt-in `HP.UseHealPrediction()` and `HP.UseAbsorbPrediction()` channels,
+  with lazy allocation, capability checks, and optional event subscriptions.
+- Independently styled healing and shield overlays on HP progress bars,
+  including direct native handling of secret amounts and clipping at bar bounds.
+- Opt-in `BlizzardUI.Hide` for stock action bars and player/target/focus frames,
+  with combat deferral and a restore callback, preserving native event handlers.
+- Cell visibility predicates and live label text, with cleanup on unmount.
+- Timer activity flags and cast/channel spell names for conditional UI rows.
+- Public `Spells` enum with named Paladin Seal spell IDs.
+- Player swing countdown sources for main-hand, off-hand, and ranged attacks,
+  driven by Forever's native swing events and native StatusBar timer animation.
+- Explicit unknown timing before the first readable event, secret-value guards,
+  weapon-change resets, and source disposal.
+- Label and Icon primitives, with event-driven texture sources.
+- Native duration sources for aura timers, spell/global cooldowns, and cast/channel
+  countdowns. Selected aura icons share the aura source's selection policy.
+
+### Fixed
+
+- Initialize native timer and swing bars with a normalized 0–1 range instead
+  of the default resource range.
+- Mount lifecycle now runs datasource binding cleanup callbacks on unmount.
+
+### Validation and limitations
+
+- Lua tests cover conditional activation/reactivation, secret callback guards,
+  optional prediction reads/events, overlay placement, and unmount cleanup.
+- Prediction amounts require the client's native unit APIs. Incoming healing
+  is raw (not reduced by heal-absorb debuffs); overheal is visually clipped.
+  HP overrides are incompatible with prediction overlays. In-game prediction
+  visuals still need validation in Forever.
+
+## 0.1.4 — 2026-10-14
+
+### Added
+
+- Class-based stores with optional stable tokens, one-time readonly snapshots,
+  transactional callback updates, and observer subscriptions.
+- Memory-only stores when no token is declared; SavedVariables-backed records
+  when a token and registry persistence configuration are provided.
+- SavedVariables initialization after the owning addon's `ADDON_LOADED` event,
+  default restoration, collision checks, and serializable data validation.
+
 ## 0.1.3 — 2026-10-14
 
 ### Added

package/README.md

@@ -94,6 +94,118 @@ function App() {
 wuira.Mount(App);
 ```
 
+### Conditional sources and health predictions
+
+```tsx
+import { UI } from "wuira";
+import { ProgressBar } from "wuira/ui";
+import { HP, Unit } from "wuira/datasources";
+
+const hp = new HP(Unit.Player)
+    .UseHealPrediction()
+    .UseAbsorbPrediction()
+    .When(value => value >= 20); // Current health points, not a percentage.
+
+const view = (
+    <ProgressBar width={220} height={24} source={hp}
+        healPrediction={{ texture: "blizzard", color: { r: 0.4, g: 1, b: 0.5, a: 0.5 } }}
+        absorbPrediction={{ texture: "solid", color: { r: 0.8, g: 0.9, b: 1, a: 0.55 } }} />
+);
+```
+
+Configure sources before mounting. `.When()` filters native binding updates using
+the source's own value; repeated calls combine with AND. A false condition hides
+the bound bar and suppresses writes until a relevant event makes it true again.
+The basic health events remain subscribed so the source can reactivate; there is
+no health polling. Predicates should depend on this source's event-driven state,
+not unrelated mutable values. `.Value` remains a fresh, checked snapshot rather
+than a filtered subscription. Secret values never reach condition callbacks:
+a conditional binding becomes inactive until readable data returns. Without a
+condition, opaque values continue directly to native widgets.
+
+Each prediction channel is allocated and its event registered only when explicitly
+enabled and supported. No prediction snapshots are cached. Access
+`hp.HealPrediction?.Value` and `hp.AbsorbPrediction?.Value` when readable, or check
+the channel's `IsAvailable` flag. Direct reads retain the usual secret-value guard.
+The APIs provide incoming healing and existing damage-absorb shields, not a
+forecast of future damage. The adapter uses
+[Blizzard's unit prediction APIs](https://github.com/Gethe/wow-ui-source/blob/live/Interface/AddOns/Blizzard_APIDocumentationGenerated/UnitDocumentation.lua).
+
+Enabled channels draw by default; `healPrediction={false}` or
+`absorbPrediction={false}` suppresses an individual overlay. Incoming healing starts
+at the native health-fill edge and clips at the bar boundary. Shields overlay
+inward from the opposite edge, remaining visible even at full health. Both accept
+independent textures/colors and support horizontal, vertical, and reversed bars.
+There is no arithmetic on secret health or prediction amounts. Raw incoming heals
+are not reduced by heal-absorb debuffs; overheal is visually clipped. Prediction
+overlays require the native health scale, so min/max/current overrides are rejected.
+Prediction reads pause while the parent HP condition is inactive. The renderer
+cleans up the overlays and resource subscriptions on unmount.
+
+### Native aura, cooldown, and cast timers
+
+```tsx
+import { UI, Spells } from "wuira";
+import { FlowLayout, ProgressBar, Icon, Label } from "wuira/ui";
+import { AuraTimer, GlobalCooldown, CastTimer, Unit } from "wuira/datasources";
+
+const aura = new AuraTimer(Unit.Player, { spellIds: [Spells.SealOfRighteousness], filter: "HELPFUL" });
+const gcd = new GlobalCooldown();
+const cast = new CastTimer(Unit.Player);
+
+function Timers() {
+    return (
+        <FlowLayout width={200} height={94} direction="vertical" gap={2}>
+            <Icon width={24} height={24} textureSource={aura.Texture} />
+            <ProgressBar height={24} source={aura}><Label text="Aura" /></ProgressBar>
+            <ProgressBar height={18} source={gcd} />
+            <ProgressBar height={22} source={cast} />
+        </FlowLayout>
+    );
+}
+```
+
+These timers pass opaque native duration objects to `SetTimerDuration`; they do
+not calculate restricted durations in Lua. `SpellCooldown(spellId)` tracks a
+specific spell, and `GlobalCooldown` supplies the GCD identifier internally.
+`CastTimer` follows casts and channels. `AuraTimer` resolves localized spell names
+and exposes an associated `Texture` source, with status indicating active,
+inactive, restricted, or unavailable data. Aura access still follows the client's
+restrictions; missing readable data is not reconstructed from combat events.
+`Label` and `Icon` are visual Cells. Application code supplies which spells to
+track; native API declarations and reads remain in wuira.
+
+### Swing timers
+
+```tsx
+import { UI, wuira } from "wuira";
+import { ProgressBar } from "wuira/ui";
+import { SwingTimer, SwingHand } from "wuira/datasources";
+
+const mainHand = new SwingTimer(SwingHand.MainHand);
+const view = wuira.Mount(<ProgressBar width={200} height={12} source={mainHand} />);
+
+// Other choices: SwingHand.OffHand and SwingHand.Ranged.
+// mainHand.Value: remaining seconds; Max.Value: duration; Percent.Value: remaining percent.
+// When removing the feature:
+if (view !== undefined) wuira.Unmount(view);
+mainHand.Dispose();
+```
+
+This source follows the player's `PLAYER_SWING(duration, swingType)` events.
+It does not reconstruct swings from the combat log or track enemy attack cycles.
+`HasTiming` is false until the first readable event and after a weapon/world reset;
+zero before that event is not evidence of a synchronized swing. After a recorded
+cycle expires, remaining time reaches zero. Secret payloads block datasource
+computation until a readable event or reset arrives.
+
+Native progress binding uses `C_DurationUtil` and `StatusBar:SetTimerDuration`,
+with no Lua per-frame animation. Range/current overrides are not supported for
+this binding. Unmount detaches each bar; call `Dispose()` to stop the source's
+event listener when its owning feature ends. Support is capability-checked;
+actual timing still needs validation in Forever. The adapter follows the
+[Forever swing API definition](https://github.com/Gethe/wow-ui-source/blob/bd2470aed543f72697a044e989285b6c83e63f73/Interface/AddOns/Blizzard_APIDocumentationGenerated/SwingTimerDocumentation.lua).
+
 ### Group members
 
 ```ts
@@ -309,6 +421,75 @@ Relative output paths resolve from the project directory. Absolute paths can tar
 
 The CLI, configuration, and build plugin use ESM (`.mjs`). Only Lua and TOC files are needed in game. `npm run build` in the framework repository generates distributable Lua modules and TypeScript declarations in `lib/`; addon builds include the framework modules they import.
 
+## Stores
+
+Use data classes to define defaults. Without a static token, records live only
+in memory and are keyed by the class itself:
+
+```ts
+import { Store, StoreRegistry } from "wuira/store";
+
+class SessionSettings extends Store {
+    CastSpellId = 1232;
+}
+
+const store = new StoreRegistry();
+const snapshot = store.get(SessionSettings); // One-time, deeply readonly copy.
+
+const unsubscribe = store.subscribe(SessionSettings, settings => {
+    console.log("New spell:", settings.CastSpellId);
+});
+
+store.set(SessionSettings, settings => {
+    settings.CastSpellId = 635;
+    return settings;
+});
+
+unsubscribe();
+```
+
+`get()` does not subscribe. `subscribe()` observes future commits and returns an
+unsubscribe function; call `get()` for initial data. Each subscriber receives an
+independent snapshot. `set()` works on a detached draft, validates the returned
+data, commits it, and sends one notification per observer. If the updater throws,
+the previous record is preserved. Stores contain data fields, not class methods.
+
+For persistence, declare a stable token and the owning addon's SavedVariables:
+
+```toc
+## SavedVariables: LumaUIDB
+```
+
+```ts
+class LumaSettings extends Store {
+    static readonly Token = "luma.settings";
+    CastSpellId = 1232;
+    Width = 220;
+}
+
+const store = new StoreRegistry({ addon: "LumaUI", variable: "LumaUIDB" });
+store.onReady(() => {
+    console.log(store.get(LumaSettings).Width);
+    store.set(LumaSettings, settings => {
+        settings.Width = 240;
+        return settings;
+    });
+});
+```
+
+Add the TOC declaration to the addon's `addon.toc.in`. The registry waits for
+`ADDON_LOADED` before opening persistent records. Tokenless records can still be
+used immediately. WoW writes the saved table on normal logout/reload; `set()`
+does not force a disk flush. Keep tokens stable across versions. New default
+fields are filled in and incompatible saved field types fall back to defaults;
+renaming keys or changing schema meaning still requires an application migration.
+
+Supported values are finite numbers, strings, booleans, arrays, and nested data
+objects. Functions, cycles, and secret values cannot be saved. Two classes cannot
+claim the same token within a registry. Share one registry instance per database.
+`Dispose()` removes its observers and pending initialization listener. Profile
+selection, schema migrations, and reactive widget binding are separate features.
+
 ## Development
 
 ```sh

package/lib/Spells.d.ts

@@ -0,0 +1,10 @@
+/** Representative spell IDs; aura sources resolve localized names across ranks. */
+export declare enum Spells {
+    SealOfRighteousness = 21084,
+    SealOfTheCrusader = 21082,
+    SealOfCommand = 20375,
+    SealOfJustice = 20164,
+    SealOfLight = 20165,
+    SealOfWisdom = 20166,
+    SealOfFury = 20163
+}

package/lib/Spells.lua

@@ -0,0 +1,19 @@
+--[[ Generated with https://github.com/TypeScriptToLua/TypeScriptToLua ]]
+local ____exports = {}
+--- Representative spell IDs; aura sources resolve localized names across ranks.
+____exports.Spells = ____exports.Spells or ({})
+____exports.Spells.SealOfRighteousness = 21084
+____exports.Spells[____exports.Spells.SealOfRighteousness] = "SealOfRighteousness"
+____exports.Spells.SealOfTheCrusader = 21082
+____exports.Spells[____exports.Spells.SealOfTheCrusader] = "SealOfTheCrusader"
+____exports.Spells.SealOfCommand = 20375
+____exports.Spells[____exports.Spells.SealOfCommand] = "SealOfCommand"
+____exports.Spells.SealOfJustice = 20164
+____exports.Spells[____exports.Spells.SealOfJustice] = "SealOfJustice"
+____exports.Spells.SealOfLight = 20165
+____exports.Spells[____exports.Spells.SealOfLight] = "SealOfLight"
+____exports.Spells.SealOfWisdom = 20166
+____exports.Spells[____exports.Spells.SealOfWisdom] = "SealOfWisdom"
+____exports.Spells.SealOfFury = 20163
+____exports.Spells[____exports.Spells.SealOfFury] = "SealOfFury"
+return ____exports

package/lib/datasources/AuraTimer.d.ts

@@ -0,0 +1,21 @@
+import { TimerSource } from "./TimerSource";
+import { TextureSource } from "./TextureSource";
+import { UnitSource } from "./UnitSource";
+import type { UnitInput } from "./UnitSource";
+export interface AuraTimerOptions {
+    /** Spell IDs resolve to localized names, so different ranks share a lookup. */
+    spellIds: readonly number[];
+    filter?: "HELPFUL" | "HARMFUL" | "HELPFUL|PLAYER" | "HARMFUL|PLAYER";
+}
+export type AuraTimerStatus = "active" | "inactive" | "restricted" | "unavailable";
+/** Selected aura duration and icon; selection policy belongs to the application. */
+export declare class AuraTimer extends TimerSource {
+    private readonly options;
+    readonly target: UnitSource;
+    readonly Texture: TextureSource;
+    private status;
+    constructor(unit: UnitInput, options: AuraTimerOptions);
+    get Status(): AuraTimerStatus;
+    private ReadAura;
+    private ReadDuration;
+}

package/lib/datasources/AuraTimer.lua

@@ -0,0 +1,322 @@
+--[[ Generated with https://github.com/TypeScriptToLua/TypeScriptToLua ]]
+-- Lua Library inline imports
+local function __TS__Class(self)
+    local c = {prototype = {}}
+    c.prototype.__index = c.prototype
+    c.prototype.constructor = c
+    return c
+end
+
+local function __TS__ClassExtends(target, base)
+    target.____super = base
+    local staticMetatable = setmetatable({__index = base}, base)
+    setmetatable(target, staticMetatable)
+    local baseMetatable = getmetatable(base)
+    if baseMetatable then
+        if type(baseMetatable.__index) == "function" then
+            staticMetatable.__index = baseMetatable.__index
+        end
+        if type(baseMetatable.__newindex) == "function" then
+            staticMetatable.__newindex = baseMetatable.__newindex
+        end
+    end
+    setmetatable(target.prototype, base.prototype)
+    if type(base.prototype.__index) == "function" then
+        target.prototype.__index = base.prototype.__index
+    end
+    if type(base.prototype.__newindex) == "function" then
+        target.prototype.__newindex = base.prototype.__newindex
+    end
+    if type(base.prototype.__tostring) == "function" then
+        target.prototype.__tostring = base.prototype.__tostring
+    end
+end
+
+local function __TS__New(target, ...)
+    local instance = setmetatable({}, target.prototype)
+    instance:____constructor(...)
+    return instance
+end
+
+local function __TS__CloneDescriptor(____bindingPattern0)
+    local value
+    local writable
+    local set
+    local get
+    local configurable
+    local enumerable
+    enumerable = ____bindingPattern0.enumerable
+    configurable = ____bindingPattern0.configurable
+    get = ____bindingPattern0.get
+    set = ____bindingPattern0.set
+    writable = ____bindingPattern0.writable
+    value = ____bindingPattern0.value
+    local descriptor = {enumerable = enumerable == true, configurable = configurable == true}
+    local hasGetterOrSetter = get ~= nil or set ~= nil
+    local hasValueOrWritableAttribute = writable ~= nil or value ~= nil
+    if hasGetterOrSetter and hasValueOrWritableAttribute then
+        error("Invalid property descriptor. Cannot both specify accessors and a value or writable attribute.", 0)
+    end
+    if get or set then
+        descriptor.get = get
+        descriptor.set = set
+    else
+        descriptor.value = value
+        descriptor.writable = writable == true
+    end
+    return descriptor
+end
+
+local __TS__DescriptorGet
+do
+    local getmetatable = _G.getmetatable
+    local ____rawget = _G.rawget
+    function __TS__DescriptorGet(self, metatable, key)
+        while metatable do
+            local rawResult = ____rawget(metatable, key)
+            if rawResult ~= nil then
+                return rawResult
+            end
+            local descriptors = ____rawget(metatable, "_descriptors")
+            if descriptors then
+                local descriptor = descriptors[key]
+                if descriptor ~= nil then
+                    if descriptor.get then
+                        return descriptor.get(self)
+                    end
+                    return descriptor.value
+                end
+            end
+            metatable = getmetatable(metatable)
+        end
+    end
+end
+
+local __TS__DescriptorSet
+do
+    local getmetatable = _G.getmetatable
+    local ____rawget = _G.rawget
+    local rawset = _G.rawset
+    function __TS__DescriptorSet(self, metatable, key, value)
+        while metatable do
+            local descriptors = ____rawget(metatable, "_descriptors")
+            if descriptors then
+                local descriptor = descriptors[key]
+                if descriptor ~= nil then
+                    if descriptor.set then
+                        descriptor.set(self, value)
+                    else
+                        if descriptor.writable == false then
+                            error(
+                                ((("Cannot assign to read only property '" .. key) .. "' of object '") .. tostring(self)) .. "'",
+                                0
+                            )
+                        end
+                        descriptor.value = value
+                    end
+                    return
+                end
+            end
+            metatable = getmetatable(metatable)
+        end
+        rawset(self, key, value)
+    end
+end
+
+local __TS__SetDescriptor
+do
+    local getmetatable = _G.getmetatable
+    local function descriptorIndex(self, key)
+        return __TS__DescriptorGet(
+            self,
+            getmetatable(self),
+            key
+        )
+    end
+    local function descriptorNewIndex(self, key, value)
+        return __TS__DescriptorSet(
+            self,
+            getmetatable(self),
+            key,
+            value
+        )
+    end
+    function __TS__SetDescriptor(target, key, desc, isPrototype)
+        if isPrototype == nil then
+            isPrototype = false
+        end
+        local ____isPrototype_0
+        if isPrototype then
+            ____isPrototype_0 = target
+        else
+            ____isPrototype_0 = getmetatable(target)
+        end
+        local metatable = ____isPrototype_0
+        if not metatable then
+            metatable = {}
+            setmetatable(target, metatable)
+        end
+        if not isPrototype and not rawget(metatable, "_isOwnDescriptorMetatable") then
+            local instanceMetatable = {}
+            instanceMetatable._isOwnDescriptorMetatable = true
+            setmetatable(instanceMetatable, metatable)
+            setmetatable(target, instanceMetatable)
+            metatable = instanceMetatable
+        end
+        local value = rawget(target, key)
+        if value ~= nil then
+            rawset(target, key, nil)
+        end
+        if not rawget(metatable, "_descriptors") then
+            metatable._descriptors = {}
+        end
+        metatable._descriptors[key] = __TS__CloneDescriptor(desc)
+        metatable.__index = descriptorIndex
+        metatable.__newindex = descriptorNewIndex
+    end
+end
+-- End of Lua Library inline imports
+local ____exports = {}
+local ____TimerSource = require("datasources.TimerSource")
+local TimerSource = ____TimerSource.TimerSource
+local ____TextureSource = require("datasources.TextureSource")
+local TextureSource = ____TextureSource.TextureSource
+local ____UnitSource = require("datasources.UnitSource")
+local resolveUnit = ____UnitSource.resolveUnit
+--- Selected aura duration and icon; selection policy belongs to the application.
+____exports.AuraTimer = __TS__Class()
+local AuraTimer = ____exports.AuraTimer
+AuraTimer.name = "AuraTimer"
+__TS__ClassExtends(AuraTimer, TimerSource)
+function AuraTimer.prototype.____constructor(self, unit, options)
+    local target = resolveUnit(nil, unit)
+    local events = {
+        "UNIT_AURA",
+        "PLAYER_ENTERING_WORLD",
+        "PLAYER_TARGET_CHANGED",
+        "PLAYER_FOCUS_CHANGED",
+        "SPELLS_CHANGED"
+    }
+    TimerSource.prototype.____constructor(
+        self,
+        function() return self:ReadDuration() end,
+        events,
+        target.Token
+    )
+    self.options = options
+    self.status = "inactive"
+    self.target = target
+    self.Texture = __TS__New(
+        TextureSource,
+        function()
+            local ____opt_0 = self:ReadAura()
+            return ____opt_0 and ____opt_0.icon
+        end,
+        events,
+        target.Token
+    )
+end
+function AuraTimer.prototype.ReadAura(self)
+    local query = C_UnitAuras and C_UnitAuras.GetAuraDataBySpellName
+    local getName = C_Spell and C_Spell.GetSpellName
+    if query == nil or getName == nil then
+        self.status = "unavailable"
+        return nil
+    end
+    do
+        local function ____catch()
+            self.status = "unavailable"
+        end
+        local ____try, ____hasReturned, ____returnValue = pcall(function()
+            for ____, id in ipairs(self.options.spellIds) do
+                do
+                    local __continue8
+                    repeat
+                        local name = getName(id)
+                        if issecretvalue(name) then
+                            self.status = "restricted"
+                            return true, nil
+                        end
+                        if name == nil then
+                            __continue8 = true
+                            break
+                        end
+                        local aura = query(self.target.Token, name, self.options.filter or "HELPFUL")
+                        if issecretvalue(aura) then
+                            self.status = "restricted"
+                            return true, nil
+                        end
+                        if aura ~= nil then
+                            self.status = "active"
+                            return true, aura
+                        end
+                        __continue8 = true
+                    until true
+                    if not __continue8 then
+                        break
+                    end
+                end
+            end
+            local ____opt_6 = C_Secrets and C_Secrets.ShouldAurasBeSecret
+            local restricted = ____opt_6 and ____opt_6()
+            self.status = (issecretvalue(restricted) or restricted == true) and "restricted" or "inactive"
+        end)
+        if not ____try then
+            ____hasReturned, ____returnValue = ____catch()
+        end
+        if ____hasReturned then
+            return ____returnValue
+        end
+    end
+    return nil
+end
+function AuraTimer.prototype.ReadDuration(self)
+    local aura = self:ReadAura()
+    if aura == nil then
+        return nil
+    end
+    do
+        local function ____catch()
+            self.status = "unavailable"
+            return true, nil
+        end
+        local ____try, ____hasReturned, ____returnValue = pcall(function()
+            local id = aura.auraInstanceID
+            if (C_UnitAuras and C_UnitAuras.GetAuraDuration) ~= nil and (issecretvalue(id) or id ~= nil) then
+                return true, C_UnitAuras.GetAuraDuration(self.target.Token, id)
+            end
+            local total = aura.duration
+            local ____end = aura.expirationTime
+            if issecretvalue(total) or issecretvalue(____end) then
+                self.status = "restricted"
+                return true, nil
+            end
+            if total == nil or ____end == nil or total <= 0 then
+                return true, nil
+            end
+            if C_DurationUtil == nil then
+                self.status = "unavailable"
+                return true, nil
+            end
+            local timer = C_DurationUtil.CreateDuration()
+            timer:SetTimeFromStart(____end - total, total)
+            return true, timer
+        end)
+        if not ____try then
+            ____hasReturned, ____returnValue = ____catch()
+        end
+        if ____hasReturned then
+            return ____returnValue
+        end
+    end
+end
+__TS__SetDescriptor(
+    AuraTimer.prototype,
+    "Status",
+    {get = function(self)
+        self:ReadAura()
+        return self.status
+    end},
+    true
+)
+return ____exports

package/lib/datasources/CastTimer.d.ts

@@ -0,0 +1,9 @@
+import { TimerSource } from "./TimerSource";
+import { UnitSource } from "./UnitSource";
+import type { UnitInput } from "./UnitSource";
+/** Remaining cast/channel time using the native duration object. */
+export declare class CastTimer extends TimerSource {
+    readonly target: UnitSource;
+    get SpellName(): string;
+    constructor(unit?: UnitInput);
+}