Add knowledge base for WoW: Midnight API changes

MIDNIGHT_API_CHANGES.md

@@ -0,0 +1,71 @@
+# WoW: Midnight (12.0) API Changes and Addon Integration
+
+This document outlines the API changes introduced in World of Warcraft: Midnight (Patch 12.0.0+) and how they affect the UI addons, specifically focusing on action bars (via `LibActionButton-1.0`) and unit frames (via `oUF`).
+
+## General Detection
+The expansion can be detected by checking if the interface version from `GetBuildInfo()` is greater than or equal to `120000`:
+```lua
+local Midnight = (select(4, GetBuildInfo())) >= 120000
+```
+TOC Interface version for Midnight is `120000` (e.g. `120001`, `120005`, `120007`).
+
+## Action Bars & Spells (LibActionButton-1.0)
+Midnight introduces several API changes to action bars and spells, moving many global functions into the `C_ActionBar` and `C_Spell` namespaces, and heavily modifying how cooldowns and charges are retrieved and displayed.
+
+### 1. The `C_ActionBar` and `C_Spell` Namespaces
+Functions that were historically global or part of older systems have been reorganized:
+- **Action Display Counts**: `GetActionCount()` is deprecated in Midnight due to its inability to deal with securely restricted "secrets". It has been replaced by:
+  - `C_ActionBar.GetActionDisplayCount(actionID)`
+  - `C_Spell.GetSpellDisplayCount(spellID)`
+
+### 2. Cooldown and Charge Duration APIs
+In Patch 12.0, the game introduces new duration object APIs to handle cooldowns and charges more robustly:
+- **Action Bars:**
+  - `C_ActionBar.GetActionChargeDuration(actionID)`
+  - `C_ActionBar.GetActionCooldownDuration(actionID)`
+  - `C_ActionBar.GetActionLossOfControlCooldownDuration(actionID)`
+- **Spells:**
+  - `C_Spell.GetSpellChargeDuration(spellID)`
+  - `C_Spell.GetSpellCooldownDuration(spellID)`
+  - `C_Spell.GetSpellLossOfControlCooldownDuration(spellID)`
+
+### 3. Cooldown Application Helper
+A new global helper function `ActionButton_ApplyCooldown` was added in 12.0 to simplify applying cooldowns to action buttons. It handles the base cooldown, charge cooldown, and loss-of-control cooldown in a single call:
+```lua
+if ActionButton_ApplyCooldown then
+    ActionButton_ApplyCooldown(self.cooldown, cooldownInfo, self.chargeCooldown, chargeInfo, self.lossOfControlCooldown, lossOfControlInfo)
+end
+```
+
+### 4. Event Changes
+- `LEARNED_SPELL_IN_TAB` is deprecated. Addons should register for `LEARNED_SPELL_IN_SKILL_LINE` instead.
+
+### 5. Button Glow Updates
+The `LibButtonGlow-1.0` library disables dimming the overlay glow based on cooldown duration in Midnight. The logic for dimming glows on buttons with long cooldowns (to avoid GCD dimming) is bypassed for Midnight, implying an internal handling change or visual update by Blizzard.
+
+## Unit Frames (oUF)
+For Unit Frames, Midnight primarily continues the transition towards structured `C_*` namespaces.
+
+### 1. `C_Spell` Integration for Costs
+Power costs for spells used in power prediction or additional power tracking now rely on the `C_Spell` namespace:
+- `C_Spell.GetSpellPowerCost(spellID)` replaces older ways of fetching power costs.
+- Max cumulative aura applications are fetched via `C_Spell.GetSpellMaxCumulativeAuraApplications(spellID)`.
+
+### 2. Secrets API (Upcoming/WIP)
+With Midnight adding more security around unit tokens, comparing unit tokens securely is moving away from direct comparisons or `pcall` workarounds toward `C_Secrets.CanCompareUnitTokens(unit1, unit2)`. (Noted as a TODO in `oUF`).
+
+### 3. Aura Management (`C_UnitAuras`)
+While `C_UnitAuras` was introduced prior to Midnight, it remains the standard for aura processing (buffs/debuffs) in `oUF`. Usage includes:
+- `C_UnitAuras.GetAuraDataBySlot(unit, slot)`
+- `C_UnitAuras.GetAuraDataByAuraInstanceID(unit, auraInstanceID)`
+- `C_UnitAuras.GetAuraDispelTypeColor(...)`
+- `C_UnitAuras.IsAuraFilteredOutByInstanceID(...)`
+
+## Summary
+To ensure compatibility with WoW: Midnight, addon authors must:
+1. Update `.toc` files to `120000+`.
+2. Replace `GetActionCount` with `C_ActionBar.GetActionDisplayCount` / `C_Spell.GetSpellDisplayCount`.
+3. Use the new duration APIs in `C_ActionBar` and `C_Spell` for charge, cooldown, and loss-of-control durations.
+4. Adapt to `ActionButton_ApplyCooldown` for setting cooldown frame states.
+5. Use `LEARNED_SPELL_IN_SKILL_LINE` for spellbook updates.
+6. Prepare for further secret/security enforcements like `C_Secrets.CanCompareUnitTokens`.