wuira 0.3.3 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,17 @@ with the release date and highlight breaking changes explicitly.
 
 ## Unreleased
 
+## 0.4.0 — 2026-10-19
+
+### Breaking
+
+- A datasource is one Blizzard call. `UseSource(UnitHealth, "player")` reads `UnitHealth`. Composite classes are removed, including `HP`, `Mana`, `Absorb`, `Prediction`, `GroupMembers`, `GroupRoster`, `Buffs`, `Debuffs`, `KnownSpells`, `SpellSource`, `UnitSource`, `ClassSource`, `SpecSource`, `EditModeLayouts`, and the cast, aura, swing, and totem timer bundles.
+
+### Added
+
+- One source for each exposed call: group size, raid roster row, unit facts, auras, spells, totems, edit mode layouts, specializations, the spell book, casts, and channels.
+- `Range`, `ReadAuras`, and `FilterAura` are helpers. `wuira/helpers` exports them. `Range(1, 5)` returns `[1, 2, 3, 4, 5]`.
+
 ## 0.3.3 — 2026-10-19
 
 ### Breaking

package/README.md

@@ -57,18 +57,18 @@ npm run build
 Open every datasource with `UseSource`. Those classes have no public constructor.
 
 ```tsx
-import { UseSource, HP, Mana, Unit } from "wuira/datasources";
-
-const hp = UseSource(HP, Unit.Player).UsePrediction().UseAbsorb();
-const mana = UseSource(Mana, Unit.Player).UseRegenTimer();
-
-<progress height={24} source={hp} />
-<progress height={24} source={mana} />
+import { UseSource, GetNumGroupMembers, UnitHealth, GetAuraDataByIndex } from "wuira/datasources";
+import { FilterAura, Range, ReadAuras } from "wuira/helpers";
+
+const count = UseSource(GetNumGroupMembers);
+const indexes = Range(1, count.Value);
+const health = UseSource(UnitHealth, "player");
+const aura = UseSource(GetAuraDataByIndex, "target", 1, "HELPFUL");
+const auras = ReadAuras("target", "HELPFUL");
+const present = FilterAura(auras, "Fortitude");
 ```
 
-`UsePrediction()` and `UseAbsorb()` append the same `Prediction` and `Absorb` sources for that unit. Read them as `hp.Prediction` and `hp.Absorb`. Incoming heals are `UnitGetIncomingHeals`. Absorbs are `UnitGetTotalAbsorbs`. `hp.Value`, `hp.Max`, and `hp.Percent` stay the three health reads.
-
-Other sources include `AuraTimer`, `GlobalCooldown`, `CastTimer`, `SpellCooldown`, `SwingTimer`, `GroupMembers`, `PartyMembers`, `RaidMembers`, `Buffs`, `Debuffs`, `KnownSpells`, `Spells`, `UnitSource`, `ClassSource`, `SpecSource`, and `SpellSource`.
+Each source is one native call. Arguments and the returned value match that call. `Range`, `ReadAuras`, and `FilterAura` are helpers: they walk or query values the caller already has. `TimerSource` still binds a native duration to a progress bar or cooldown.
 
 ## Layout
 
@@ -97,14 +97,17 @@ Supported action types: `spell`, `item`, `macro`, `action`, and `target`. Action
 ```tsx
 import { UI } from "wuira/ui";
 import { Nameplates } from "wuira/skins";
-import { UseSource, HP } from "wuira/datasources";
+import { UseSource, UnitHealth } from "wuira/datasources";
 
 const plates = Nameplates
     .Apply(p => p.GUID === configuredGUID, p => {
         if (p.Native.healthBar) p.Size(p.Native.healthBar, 140, 12);
     })
     .Replace(() => true, p => (
-        <progress width={140} height={12} source={UseSource(HP, p.Unit)} />
+        <cell width={140} height={12} onMount={() => {
+            const health = UseSource(UnitHealth, p.Unit);
+            return () => health.Dispose();
+        }} />
     ));
 
 // plates.Dispose();

package/docs/source-converters.md

@@ -3,12 +3,12 @@
 `SourceConverter` transforms a readable source with a typed callback. It consumes change notifications, shares one upstream subscription across observers, and does not create a timer or dispose the shared input. Sources without notifications remain available as checked one-time reads.
 
 ```ts
-import { UseSource, SourceConverter, HP, ClassSource, Unit } from "wuira/datasources";
+import { UseSource, SourceConverter, UnitHealth, UnitClass } from "wuira/datasources";
 
-const hp = UseSource(HP, Unit.Player);
+const hp = UseSource(UnitHealth, "player");
 const doubled = UseSource(SourceConverter, hp, value => value * 2);
-const characterClass = UseSource(ClassSource, Unit.Player);
-const token = UseSource(SourceConverter, characterClass, info => info?.token);
+const characterClass = UseSource(UnitClass, "player");
+const token = UseSource(SourceConverter, characterClass, info => info.classFile);
 const stop = doubled.BindTo(value => console.log(value));
 
 // On removal:
@@ -22,6 +22,6 @@ characterClass.Dispose();
 
 `onChange()` observes future readable output changes; `BindTo()` also applies the current readable value immediately. Identical scalar outputs do not emit again. `When()` filters emissions without changing the checked getter. `Dispose()` releases observers while leaving the input available to other consumers.
 
-Restricted values, including nested secret fields, never reach a conversion callback. Restrictions are checked when consumed; combat alone does not mark a value secret. ClassSource subscriptions follow unit identity changes and native events, releasing listeners when the last consumer unsubscribes.
+Restricted values, including nested secret fields, never reach a conversion callback. Restrictions are checked when consumed; combat alone does not mark a value secret. A native source is a pull of one call. It notifies a converter only when that source exposes `onChange`.
 
 The SDK accepts TypeScript callbacks. Editable case rules and math formulas are LumaUI builder factories, implemented using this generic source. Converters produce data; protected button actions remain subject to native combat restrictions.

package/docs/spells.md

@@ -22,7 +22,7 @@ effects and records whose ownership cannot be established from these tables.
 No heuristic turns every unclassified record into an NPC-only spell.
 Class-family membership does not prove that a spell is learnable by a player.
 The snapshot includes retired, test and hidden records still present in this
-Forever client's tables. Use KnownSpells for a character's learned abilities.
+Forever client's tables. Learned spells come from the spell book calls, one row at a time.
 
 Every ID has an explicit ID-suffixed member. Rank labels come from the client.
 Short aliases select the lowest linked rank; ambiguous unranked names require

package/lib/datasources/NativeApi.d.ts

@@ -0,0 +1,319 @@
+import { Source } from "./Source";
+export interface UnitName {
+    readonly name: string | undefined;
+    readonly realm: string | undefined;
+}
+/** Fields named by `GetRaidRosterInfo`. No identity or pet is added. */
+export interface RaidRosterInfo {
+    readonly name: string | undefined;
+    readonly rank: number | undefined;
+    readonly subgroup: number | undefined;
+    readonly level: number | undefined;
+    readonly className: string | undefined;
+    readonly fileName: string | undefined;
+    readonly zone: string | undefined;
+    readonly online: boolean | undefined;
+    readonly isDead: boolean | undefined;
+    readonly role: string | undefined;
+    readonly isML: boolean | undefined;
+}
+/** Fields returned by `C_UnitAuras.GetAuraDataByIndex`. */
+export interface AuraData {
+    readonly spellId: number;
+    readonly name: string;
+    readonly icon: number;
+    readonly sourceUnit?: string;
+}
+/** `GetNumGroupMembers`. The value is the group size, including the player. */
+export declare class GetNumGroupMembers extends Source<number, []> {
+    protected constructor();
+    protected read(): number;
+}
+/** `IsInRaid`. */
+export declare class IsInRaid extends Source<boolean, []> {
+    protected constructor();
+    protected read(): boolean;
+}
+/** `UnitGUID(unit)`. */
+export declare class UnitGUID extends Source<string | undefined, [string]> {
+    protected constructor(unit: string);
+    protected read(props: [string]): string | undefined;
+}
+/** `UnitFullName(unit)`. Both native returns are kept. */
+export declare class UnitFullName extends Source<UnitName, [string]> {
+    protected constructor(unit: string);
+    protected HasSecretFields(value: UnitName): boolean;
+    protected read(props: [string]): UnitName;
+}
+/** `UnitExists(unit)`. */
+export declare class UnitExists extends Source<boolean, [string]> {
+    protected constructor(unit: string);
+    protected read(props: [string]): boolean;
+}
+/** `GetRaidRosterInfo(index)`. One row. */
+export declare class GetRaidRosterInfo extends Source<RaidRosterInfo, [number]> {
+    protected constructor(index: number);
+    protected HasSecretFields(value: RaidRosterInfo): boolean;
+    protected read(props: [number]): RaidRosterInfo;
+}
+/** `C_UnitAuras.GetAuraDataByIndex(unit, index, filter)`. One aura, or undefined when the index is past the end. */
+export declare class GetAuraDataByIndex extends Source<AuraData | undefined, [string, number, string]> {
+    protected constructor(unit: string, index: number, filter: string);
+    protected HasSecretFields(value: AuraData | undefined): boolean;
+    protected read(props: [string, number, string]): AuraData | undefined;
+}
+/** `UnitHealth(unit)`. */
+export declare class UnitHealth extends Source<number, [string]> {
+    protected constructor(unit: string);
+    protected read(props: [string]): number;
+}
+/** `UnitHealthMax(unit)`. */
+export declare class UnitHealthMax extends Source<number, [string]> {
+    protected constructor(unit: string);
+    protected read(props: [string]): number;
+}
+/** `UnitPower(unit, powerType)`. */
+export declare class UnitPower extends Source<number, [string, number]> {
+    protected constructor(unit: string, powerType: number);
+    protected read(props: [string, number]): number;
+}
+/** `UnitPowerMax(unit, powerType)`. */
+export declare class UnitPowerMax extends Source<number, [string, number]> {
+    protected constructor(unit: string, powerType: number);
+    protected read(props: [string, number]): number;
+}
+/** `UnitGetTotalAbsorbs(unit)`. */
+export declare class UnitGetTotalAbsorbs extends Source<number, [string]> {
+    protected constructor(unit: string);
+    protected read(props: [string]): number;
+}
+/** `UnitGetIncomingHeals(unit)`. */
+export declare class UnitGetIncomingHeals extends Source<number, [string]> {
+    protected constructor(unit: string);
+    protected read(props: [string]): number;
+}
+export interface UnitClassInfo {
+    readonly name: string | undefined;
+    readonly classFile: string | undefined;
+    readonly classId: number | undefined;
+}
+/** `UnitClass(unit)`. */
+export declare class UnitClass extends Source<UnitClassInfo, [string]> {
+    protected constructor(unit: string);
+    protected HasSecretFields(value: UnitClassInfo): boolean;
+    protected read(props: [string]): UnitClassInfo;
+}
+/** `UnitIsPlayer(unit)`. */
+export declare class UnitIsPlayer extends Source<boolean, [string]> {
+    protected constructor(unit: string);
+    protected read(props: [string]): boolean;
+}
+/** `UnitIsUnit(first, second)`. */
+export declare class UnitIsUnit extends Source<boolean, [string, string]> {
+    protected constructor(first: string, second: string);
+    protected read(props: [string, string]): boolean;
+}
+/** `C_Spell.GetSpellName(spellId)`. */
+export declare class GetSpellName extends Source<string | undefined, [number | string]> {
+    protected constructor(spellId: number | string);
+    protected read(props: [number | string]): string | undefined;
+}
+/** `C_Spell.GetSpellTexture(spellId)`. */
+export declare class GetSpellTexture extends Source<number | undefined, [number | string]> {
+    protected constructor(spellId: number | string);
+    protected read(props: [number | string]): number | undefined;
+}
+/** Opaque duration object returned by `C_Spell.GetSpellCooldownDuration`. */
+export interface SpellCooldownDuration {
+    readonly __wuiraSpellCooldown: unique symbol;
+}
+/** `C_Spell.GetSpellCooldownDuration(spellId, ignoreGCD)`. */
+export declare class GetSpellCooldownDuration extends Source<SpellCooldownDuration | undefined, [number | string, boolean]> {
+    protected constructor(spellId: number | string, ignoreGCD: boolean);
+    protected read(props: [number | string, boolean]): SpellCooldownDuration | undefined;
+}
+/** `C_Spell.IsSpellPassive(spellId)`. */
+export declare class IsSpellPassive extends Source<boolean | undefined, [number | string]> {
+    protected constructor(spellId: number | string);
+    protected read(props: [number | string]): boolean | undefined;
+}
+/** `C_UnitAuras.GetAuraDataBySpellName(unit, name, filter)`. */
+export declare class GetAuraDataBySpellName extends Source<wuiraNativeAuraData | undefined, [string, string, string]> {
+    protected constructor(unit: string, name: string, filter: string);
+    protected read(props: [string, string, string]): wuiraNativeAuraData | undefined;
+}
+export interface TotemInfo {
+    readonly haveTotem: boolean | undefined;
+    readonly name: string | undefined;
+    readonly startTime: number | undefined;
+    readonly duration: number | undefined;
+    readonly icon: number | undefined;
+    readonly modRate: number | undefined;
+    readonly spellId: number | undefined;
+}
+/** `GetTotemInfo(slot)`. */
+export declare class GetTotemInfo extends Source<TotemInfo, [number]> {
+    protected constructor(slot: number);
+    protected read(props: [number]): TotemInfo;
+}
+/** `GetNumTotemSlots`. */
+export declare class GetNumTotemSlots extends Source<number, []> {
+    protected constructor();
+    protected read(): number;
+}
+export interface EditModeLayoutRow {
+    layoutName: string;
+    layoutType: number;
+    interfaceStyle?: number;
+}
+export interface EditModeLayoutList {
+    layouts: EditModeLayoutRow[];
+    activeLayout: number;
+}
+/** `C_EditMode.GetLayouts`. */
+export declare class GetLayouts extends Source<EditModeLayoutList | undefined, []> {
+    protected constructor();
+    protected read(): EditModeLayoutList | undefined;
+}
+export interface SpecializationRow {
+    readonly id: number | undefined;
+    readonly name: string | undefined;
+    readonly description: string | undefined;
+    readonly icon: number | undefined;
+    readonly role: string | undefined;
+    readonly primaryStat: number | undefined;
+    readonly pointsSpent: number | undefined;
+}
+/** `C_SpecializationInfo.GetNumSpecializationsForClassID(classId)`. */
+export declare class GetNumSpecializationsForClassID extends Source<number, [number]> {
+    protected constructor(classId: number);
+    protected read(props: [number]): number;
+}
+/** `C_SpecializationInfo.GetSpecializationInfo`. One row. */
+export declare class GetSpecializationInfo extends Source<SpecializationRow, [number, boolean, boolean, string | undefined, number | undefined, number | undefined, number | undefined]> {
+    protected constructor(index: number, inspect: boolean, pet: boolean, unit?: string, sex?: number, group?: number, classId?: number);
+    protected read(props: [number, boolean, boolean, string | undefined, number | undefined, number | undefined, number | undefined]): SpecializationRow;
+}
+/** `C_SpellBook.GetNumSpellBookSkillLines`. */
+export declare class GetNumSpellBookSkillLines extends Source<number, []> {
+    protected constructor();
+    protected read(): number;
+}
+/** `C_SpellBook.GetSpellBookItemInfo(slot, bank)`. */
+export declare class GetSpellBookItemInfo extends Source<{
+    itemType: number;
+    spellID?: number;
+    name?: string;
+    isOffSpec?: boolean;
+    isPassive?: boolean;
+} | undefined, [number, number]> {
+    protected constructor(slot: number, bank: number);
+    protected read(props: [number, number]): {
+        itemType: number;
+        spellID?: number;
+        name?: string;
+        isOffSpec?: boolean;
+        isPassive?: boolean;
+    } | undefined;
+}
+/** Opaque object returned by native duration calls. */
+export interface NativeDurationHandle {
+    readonly __wuiraNativeDuration: unique symbol;
+}
+export interface SpellTabInfo {
+    readonly name: string | undefined;
+    readonly texture: number | undefined;
+    readonly offset: number | undefined;
+    readonly numSlots: number | undefined;
+}
+export interface SpellPowerCost {
+    readonly type: number;
+    readonly cost?: number;
+}
+export interface SpellBookSkillLine {
+    readonly itemIndexOffset: number;
+    readonly numSpellBookItems: number;
+}
+export interface CastInfo {
+    readonly name: string | undefined;
+    readonly text: string | undefined;
+    readonly texture: number | undefined;
+    readonly startTimeMS: number | undefined;
+    readonly endTimeMS: number | undefined;
+    readonly isTradeSkill: boolean | undefined;
+    readonly castID: string | undefined;
+    readonly notInterruptible: boolean | undefined;
+    readonly spellId: number | undefined;
+}
+export interface ChannelInfo {
+    readonly name: string | undefined;
+    readonly text: string | undefined;
+    readonly texture: number | undefined;
+    readonly startTimeMS: number | undefined;
+    readonly endTimeMS: number | undefined;
+    readonly isTradeSkill: boolean | undefined;
+    readonly notInterruptible: boolean | undefined;
+    readonly spellId: number | undefined;
+}
+/** `UnitHealthPercent(unit, predicted, curve)`. */
+export declare class UnitHealthPercent extends Source<number, [string, boolean, unknown]> {
+    protected constructor(unit: string, predicted: boolean, curve: unknown);
+    protected read(props: [string, boolean, unknown]): number;
+}
+/** `UnitPowerPercent(unit, powerType, predicted, curve)`. */
+export declare class UnitPowerPercent extends Source<number, [string, number, boolean, unknown]> {
+    protected constructor(unit: string, powerType: number, predicted: boolean, curve: unknown);
+    protected read(props: [string, number, boolean, unknown]): number;
+}
+/** `UnitCastingDuration(unit)`. */
+export declare class UnitCastingDuration extends Source<NativeDurationHandle | undefined, [string]> {
+    protected constructor(unit: string);
+    protected read(props: [string]): NativeDurationHandle | undefined;
+}
+/** `UnitChannelDuration(unit)`. */
+export declare class UnitChannelDuration extends Source<NativeDurationHandle | undefined, [string]> {
+    protected constructor(unit: string);
+    protected read(props: [string]): NativeDurationHandle | undefined;
+}
+/** `UnitCastingInfo(unit)`. */
+export declare class UnitCastingInfo extends Source<CastInfo, [string]> {
+    protected constructor(unit: string);
+    protected HasSecretFields(value: CastInfo): boolean;
+    protected read(props: [string]): CastInfo;
+}
+/** `UnitChannelInfo(unit)`. */
+export declare class UnitChannelInfo extends Source<ChannelInfo, [string]> {
+    protected constructor(unit: string);
+    protected HasSecretFields(value: ChannelInfo): boolean;
+    protected read(props: [string]): ChannelInfo;
+}
+/** `GetTotemDuration(slot)`. */
+export declare class GetTotemDuration extends Source<NativeDurationHandle | undefined, [number]> {
+    protected constructor(slot: number);
+    protected read(props: [number]): NativeDurationHandle | undefined;
+}
+/** `GetNumSpellTabs`. */
+export declare class GetNumSpellTabs extends Source<number, []> {
+    protected constructor();
+    protected read(): number;
+}
+/** `GetSpellTabInfo(tab)`. */
+export declare class GetSpellTabInfo extends Source<SpellTabInfo, [number]> {
+    protected constructor(tab: number);
+    protected read(props: [number]): SpellTabInfo;
+}
+/** `C_UnitAuras.GetAuraDuration(unit, spellId)`. */
+export declare class GetAuraDuration extends Source<NativeDurationHandle | undefined, [string, number]> {
+    protected constructor(unit: string, spellId: number);
+    protected read(props: [string, number]): NativeDurationHandle | undefined;
+}
+/** `C_Spell.GetSpellPowerCost(spellId)`. */
+export declare class GetSpellPowerCost extends Source<SpellPowerCost[] | undefined, [number]> {
+    protected constructor(spellId: number);
+    protected read(props: [number]): SpellPowerCost[] | undefined;
+}
+/** `C_SpellBook.GetSpellBookSkillLineInfo(line)`. */
+export declare class GetSpellBookSkillLineInfo extends Source<SpellBookSkillLine | undefined, [number]> {
+    protected constructor(line: number);
+    protected read(props: [number]): SpellBookSkillLine | undefined;
+}