DEV: Deprecate `api.includePostAttributes` in favor of `api.addTrackedPostProperties` (#30345)

app/assets/javascripts/discourse/app/lib/plugin-api.gjs

@@ -3,7 +3,7 @@
 // docs/CHANGELOG-JAVASCRIPT-PLUGIN-API.md whenever you change the version
 // using the format described at https://keepachangelog.com/en/1.0.0/.
 
-export const PLUGIN_API_VERSION = "1.39.0";
+export const PLUGIN_API_VERSION = "1.39.1";
 
 import $ from "jquery";
 import { h } from "virtual-dom";
@@ -823,18 +823,34 @@ class PluginApi {
    *
    **/
   includePostAttributes(...attributes) {
+    deprecated(
+      "`api.includePostAttributes` has been deprecated. Use api.addTrackedPostProperties instead.",
+      {
+        id: "discourse.api.include-post-attributes",
+        since: "v3.4.0.beta3-dev",
+        dropFrom: "v3.5.0",
+      }
+    );
+
     includeAttributes(...attributes);
   }
 
   /**
-   * Adds a tracked property to the post model.
+   * Adds tracked properties to the post model.
    *
-   * This method is used to mark a property as tracked for post updates.
+   * This method is used to mark properties as tracked for post updates.
    *
-   * @param {string} name - The name of the property to track.
+   * It will also add the properties to the list of Post's attributes passed to
+   * widgets.
+   *
+   * You'll need to do this if you've added properties to a Post and want to use
+   * them when you're rendering.
+   *
+   * @param {...string} names - The names of the properties to be tracked.
    */
-  addTrackedPostProperty(name) {
-    _addTrackedPostProperty(name);
+  addTrackedPostProperties(...names) {
+    names.forEach((name) => _addTrackedPostProperty(name));
+    includeAttributes(...names); // compatibility with widget's attributes
   }
 
   /**

app/assets/javascripts/discourse/app/lib/transform-post.js

@@ -4,10 +4,10 @@ import Badge from "discourse/models/badge";
 import getURL from "discourse-common/lib/get-url";
 import { i18n } from "discourse-i18n";
 
-const _additionalAttributes = [];
+const _additionalAttributes = new Set();
 
 export function includeAttributes(...attributes) {
-  attributes.forEach((a) => _additionalAttributes.push(a));
+  attributes.forEach((a) => _additionalAttributes.add(a));
 }
 
 export function transformBasicPost(post) {

app/assets/javascripts/discourse/tests/unit/models/post-test.js

@@ -34,7 +34,7 @@ module("Unit | Model | post", function (hooks) {
 
   test("updateFromPost", function (assert) {
     withPluginApi("1.39.0", (api) => {
-      api.addTrackedPostProperty("plugin_property");
+      api.addTrackedPostProperties("plugin_property", "other_plugin_property");
     });
 
     const post = this.store.createRecord("post", {
@@ -55,6 +55,7 @@ module("Unit | Model | post", function (hooks) {
         yours: false,
         likeAction: { count: 1 },
         plugin_property: "different plugin value",
+        other_plugin_property: "other different plugin value",
       })
     );
 
@@ -69,6 +70,11 @@ module("Unit | Model | post", function (hooks) {
       "different plugin value",
       "`plugin_property` field was updated"
     );
+    assert.strictEqual(
+      post.other_plugin_property,
+      "other different plugin value",
+      "`other_plugin_property` field was updated"
+    );
   });
 
   test("destroy by staff", async function (assert) {

docs/CHANGELOG-JAVASCRIPT-PLUGIN-API.md

@@ -7,6 +7,11 @@ in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.39.1] - 2024-12-18
+
+- Renamed `addTrackedPostProperty` to `addTrackedPostProperties` to allow plugins/TCs to add multiple new tracked properties to the post model.
+- Deprecated `includePostAttributes` in favor of `addTrackedPostProperties`.
+
 ## [1.39.0] - 2024-11-27
 
 - Added `addTrackedPostProperty` which allows plugins/TCs to add a new tracked property to the post model.