wuira 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -7,6 +7,16 @@ with the release date and highlight breaking changes explicitly.
 
 ## Unreleased
 
+## 0.2.3 — 2026-10-15
+
+### Added
+
+- Tooltip attachment in Cell decorations, inherited by all visual components.
+  Route hover to native GameTooltip or another native tooltip with custom text,
+  extra lines or a callback using native spell, item, unit, hyperlink and action APIs.
+- Motion-only hover input preserves click-through behavior and existing scripts;
+  owned tooltips close on leave, hide and disposal without changing secure actions.
+
 ## 0.2.2 — 2026-10-15
 
 ### Added

package/README.md

@@ -610,6 +610,30 @@ not install event listeners or poll automatically. The current adapter requires
 in-game verification. Unit tokens refer to snapshot time and are not persistent
 caster identities. No Paladin-specific spell catalog or filtering is built in.
 
+### Native tooltips
+
+`Tooltip` attaches to any Cell through decorations. It forwards hover to the
+game's native tooltip API and creates no visual regions or update loop.
+
+```tsx
+import { Cell, Tooltip } from "wuira/ui";
+
+<Cell width={40} height={40} decorations={{
+    tooltip: new Tooltip({ text: "My tooltip", lines: [{ text: "Extra details" }] }),
+}} />;
+
+<Cell width={40} height={40} decorations={{
+    tooltip: new Tooltip({ show: tooltip => tooltip.SetSpellByID(635) }),
+}} />;
+```
+
+The same attachment works on SecureButton. Call SetItemByID, SetUnit, SetHyperlink
+or SetAction inside `show` for other native content. `text` may be a function
+evaluated on hover; `show` may return false to suppress display. Optional `target`
+selects another native tooltip, and `anchor` defaults to ANCHOR_RIGHT.
+Hover preserves click-through and existing scripts. Leave, hide and unmount close
+only a tooltip still owned by that Cell. Use one decoration instance per Cell.
+
 ### Visual styling
 
 <!-- Screenshot: a dark Cell with a thin colored border. -->

package/lib/platform/forever.d.ts

@@ -50,6 +50,8 @@ interface wuiraNativeFrame {
     SetFrameLevel(level: number): void;
     CreateFontString(name: undefined, layer: "OVERLAY"): wuiraNativeFontString;
     EnableMouse(enabled: boolean): void;
+    EnableMouseMotion(enabled: boolean): void;
+    IsMouseMotionEnabled(): boolean;
     RegisterEvent(event: string): void;
     UnregisterAllEvents(): void;
     SetScript(script: "OnEvent", handler: ((this: void, frame: wuiraNativeFrame, event: string, unit?: string) => void) | undefined): void;

package/lib/rendering/decorations.lua

@@ -38,5 +38,6 @@ function ____exports.renderDecorations(self, item, tree)
     end
     ____attach_16(nil, ____temp_15)
     attach(nil, decorations and decorations.glow)
+    attach(nil, decorations and decorations.tooltip)
 end
 return ____exports

package/lib/ui/decorations/Decorations.d.ts

@@ -1,8 +1,10 @@
 import type { Background } from "./Background";
 import type { Border } from "./Border";
 import type { Glow } from "./Glow";
+import type { Tooltip } from "./Tooltip";
 export interface Decorations {
     background?: Background;
     border?: Border;
     glow?: Glow;
+    tooltip?: Tooltip;
 }

package/lib/ui/decorations/Tooltip.d.ts

@@ -0,0 +1,50 @@
+import type { Color } from "../../types/Color";
+import { Decoration } from "./Decoration";
+export type TooltipAnchor = "ANCHOR_RIGHT" | "ANCHOR_LEFT" | "ANCHOR_TOP" | "ANCHOR_BOTTOM" | "ANCHOR_CURSOR" | "ANCHOR_NONE";
+/** Native GameTooltip surface passed to callbacks; no custom tooltip renderer. */
+export interface NativeTooltip {
+    SetOwner(owner: wuiraNativeFrame, anchor: TooltipAnchor): void;
+    IsOwned(owner: wuiraNativeFrame): boolean;
+    ClearLines(): void;
+    SetText(text: string, r?: number, g?: number, b?: number, alpha?: number, wrap?: boolean): void;
+    AddLine(text: string, r?: number, g?: number, b?: number, wrap?: boolean): void;
+    SetSpellByID(id: number): void;
+    SetItemByID(id: number): void;
+    SetUnit(unit: string): void;
+    SetHyperlink(link: string): void;
+    SetAction(slot: number): void;
+    Show(): void;
+    Hide(): void;
+}
+export interface TooltipLine {
+    text: string;
+    color?: Color;
+    wrap?: boolean;
+}
+interface TooltipOptions {
+    anchor?: TooltipAnchor;
+    /** Defaults to the game's shared GameTooltip; resolved on hover. */
+    target?: NativeTooltip | (() => NativeTooltip | undefined);
+    lines?: readonly TooltipLine[];
+}
+export type TooltipProps = TooltipOptions & ({
+    text: string | (() => string | undefined);
+    color?: Color;
+    wrap?: boolean;
+    show?: never;
+} | {
+    show: (tooltip: NativeTooltip, owner: wuiraNativeFrame) => void | false;
+    text?: never;
+});
+/** Attaches hover routing to a Cell. Creates no frames, textures or update loop. */
+export declare class Tooltip extends Decoration {
+    readonly props: TooltipProps;
+    private binding?;
+    private shown?;
+    constructor(props: TooltipProps);
+    protected draw(frame: wuiraNativeFrame): void;
+    private Show;
+    private Hide;
+    dispose(): void;
+}
+export {};

package/lib/ui/decorations/Tooltip.lua

@@ -0,0 +1,218 @@
+--[[ 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__CountVarargs(...)
+    return select("#", ...)
+end
+
+local function __TS__SparseArrayNew(...)
+    local sparseArray = {...}
+    sparseArray.sparseLength = __TS__CountVarargs(...)
+    return sparseArray
+end
+
+local function __TS__SparseArrayPush(sparseArray, ...)
+    local args = {...}
+    local argsLen = __TS__CountVarargs(...)
+    local listLen = sparseArray.sparseLength
+    for i = 1, argsLen do
+        sparseArray[listLen + i] = args[i]
+    end
+    sparseArray.sparseLength = listLen + argsLen
+end
+
+local function __TS__SparseArraySpread(sparseArray)
+    local _unpack = unpack or table.unpack
+    return _unpack(sparseArray, 1, sparseArray.sparseLength)
+end
+-- End of Lua Library inline imports
+local ____exports = {}
+local ____Decoration = require("ui.decorations.Decoration")
+local Decoration = ____Decoration.Decoration
+--- Attaches hover routing to a Cell. Creates no frames, textures or update loop.
+____exports.Tooltip = __TS__Class()
+local Tooltip = ____exports.Tooltip
+Tooltip.name = "Tooltip"
+__TS__ClassExtends(Tooltip, Decoration)
+function Tooltip.prototype.____constructor(self, props)
+    Decoration.prototype.____constructor(self)
+    self.props = props
+end
+function Tooltip.prototype.draw(self, frame)
+    local binding = {
+        frame = frame,
+        motion = frame:IsMouseMotionEnabled()
+    }
+    self.binding = binding
+    binding.enter = function() return self:Show(frame) end
+    binding.leave = function() return self:Hide() end
+    frame:HookScript(
+        "OnEnter",
+        function()
+            local ____opt_0 = binding.enter
+            return ____opt_0 and ____opt_0(binding)
+        end
+    )
+    frame:HookScript(
+        "OnLeave",
+        function()
+            local ____opt_2 = binding.leave
+            return ____opt_2 and ____opt_2(binding)
+        end
+    )
+    frame:HookScript(
+        "OnHide",
+        function()
+            local ____opt_4 = binding.leave
+            return ____opt_4 and ____opt_4(binding)
+        end
+    )
+    if not binding.motion then
+        frame:EnableMouseMotion(true)
+    end
+end
+function Tooltip.prototype.Show(self, owner)
+    self:Hide()
+    local target = self.props.target
+    local ____temp_6
+    if type(target) == "function" then
+        ____temp_6 = target(nil)
+    else
+        ____temp_6 = target or GameTooltip
+    end
+    local tooltip = ____temp_6
+    if tooltip == nil then
+        return
+    end
+    tooltip:SetOwner(owner, self.props.anchor or "ANCHOR_RIGHT")
+    self.shown = {tooltip = tooltip, owner = owner}
+    do
+        local function ____catch(failure)
+            self:Hide()
+            error(failure, 0)
+        end
+        local ____try, ____hasReturned, ____returnValue = pcall(function()
+            tooltip:ClearLines()
+            if self.props.show ~= nil then
+                if self.props:show(tooltip, owner) == false then
+                    self:Hide()
+                    return true
+                end
+            else
+                local ____temp_7
+                if type(self.props.text) == "function" then
+                    ____temp_7 = self.props:text()
+                else
+                    ____temp_7 = self.props.text
+                end
+                local text = ____temp_7
+                if text == nil then
+                    self:Hide()
+                    return true
+                end
+                local color = self.props.color or ({r = 1, g = 1, b = 1})
+                local ____tooltip_SetText_10 = tooltip.SetText
+                local ____array_9 = __TS__SparseArrayNew(
+                    text,
+                    color.r,
+                    color.g,
+                    color.b,
+                    color.a or 1
+                )
+                local ____self_props_wrap_8 = self.props.wrap
+                if ____self_props_wrap_8 == nil then
+                    ____self_props_wrap_8 = true
+                end
+                __TS__SparseArrayPush(____array_9, ____self_props_wrap_8)
+                ____tooltip_SetText_10(
+                    tooltip,
+                    __TS__SparseArraySpread(____array_9)
+                )
+            end
+            for ____, line in ipairs(self.props.lines or ({})) do
+                local color = line.color or ({r = 1, g = 1, b = 1})
+                local ____tooltip_AddLine_13 = tooltip.AddLine
+                local ____array_12 = __TS__SparseArrayNew(line.text, color.r, color.g, color.b)
+                local ____line_wrap_11 = line.wrap
+                if ____line_wrap_11 == nil then
+                    ____line_wrap_11 = true
+                end
+                __TS__SparseArrayPush(____array_12, ____line_wrap_11)
+                ____tooltip_AddLine_13(
+                    tooltip,
+                    __TS__SparseArraySpread(____array_12)
+                )
+            end
+            tooltip:Show()
+        end)
+        if not ____try then
+            ____hasReturned, ____returnValue = ____catch(____hasReturned)
+        end
+        if ____hasReturned then
+            return ____returnValue
+        end
+    end
+end
+function Tooltip.prototype.Hide(self)
+    local shown = self.shown
+    self.shown = nil
+    if shown ~= nil and shown.tooltip:IsOwned(shown.owner) then
+        shown.tooltip:Hide()
+    end
+end
+function Tooltip.prototype.dispose(self)
+    local binding = self.binding
+    self.binding = nil
+    if binding ~= nil then
+        binding.enter = nil
+        binding.leave = nil
+        local ____temp_17 = not binding.motion
+        if ____temp_17 then
+            local ____InCombatLockdown_result_16 = InCombatLockdown()
+            if ____InCombatLockdown_result_16 then
+                local ____this_15
+                ____this_15 = binding.frame
+                local ____opt_14 = ____this_15.IsProtected
+                ____InCombatLockdown_result_16 = (____opt_14 and ____opt_14(____this_15)) == true
+            end
+            ____temp_17 = not ____InCombatLockdown_result_16
+        end
+        if ____temp_17 then
+            binding.frame:EnableMouseMotion(false)
+        end
+    end
+    self:Hide()
+    Decoration.prototype.dispose(self)
+end
+return ____exports

package/lib/ui/index.d.ts

@@ -24,6 +24,8 @@ export { ProgressBar } from "./ProgressBar";
 export { Background } from "./decorations/Background";
 export { Border } from "./decorations/Border";
 export { Glow } from "./decorations/Glow";
+export { Tooltip } from "./decorations/Tooltip";
+export type { TooltipProps, TooltipAnchor, TooltipLine, NativeTooltip } from "./decorations/Tooltip";
 export { Label } from "./Label";
 export type { LabelProps } from "./Label";
 export { Icon } from "./Icon";

package/lib/ui/index.lua

@@ -68,6 +68,10 @@ do
     local ____Glow = require("ui.decorations.Glow")
     ____exports.Glow = ____Glow.Glow
 end
+do
+    local ____Tooltip = require("ui.decorations.Tooltip")
+    ____exports.Tooltip = ____Tooltip.Tooltip
+end
 do
     local ____Label = require("ui.Label")
     ____exports.Label = ____Label.Label

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wuira",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "author": {
     "name": "Kerim Cetinbas",
     "email": "a.cetinbas@icloud.com"