fix: default presence widgets to top of dashboard on fresh install

README.md

@@ -18,7 +18,7 @@ WordPress has no way to know who is logged in, what screen they are on, or which
 
 ## Try it
 
-[Test in WordPress Playground](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/WordPress/presence-api/main/blueprint.json)
+[![Open in WordPress Playground](https://playground.wordpress.net/assets/playground-badge.svg)](https://playground.wordpress.net/?blueprint-url=https://raw.githubusercontent.com/WordPress/presence-api/main/blueprint.json)
 
 Or run locally:
 

presence-api.php

@@ -120,6 +120,22 @@ function wp_presence_activate() {
 	wp_presence_schedule_cleanup();
 }
 
+/**
+ * Returns the default dashboard widget order when the user has no stored preference.
+ *
+ * @param array|false $result Stored meta value, or false if not set.
+ * @return array|false Original value, or a default order with presence widgets first.
+ */
+function wp_presence_default_widget_order( $result ) {
+	if ( $result ) {
+		return $result;
+	}
+	return array(
+		'normal' => 'presence_whos_online,presence_active_posts,dashboard_right_now,dashboard_activity',
+		'side'   => 'dashboard_quick_press,dashboard_primary',
+	);
+}
+
 /**
  * Cleans up on plugin deactivation.
  */
@@ -164,6 +180,7 @@ function wp_presence_deactivate() {
 
 add_action( 'admin_init', 'wp_presence_register_post_list_columns' );
 
+add_filter( 'get_user_option_meta-box-order_dashboard', 'wp_presence_default_widget_order' );
 add_action( 'wp_dashboard_setup', array( 'WP_Presence_Widget_Whos_Online', 'register' ) );
 add_filter( 'heartbeat_received', array( 'WP_Presence_Widget_Whos_Online', 'heartbeat_received' ), 10, 3 );
 add_action( 'wp_dashboard_setup', array( 'WP_Presence_Widget_Active_Posts', 'register' ) );

tests/test-dashboard-widget-order.php

@@ -0,0 +1,67 @@
+<?php
+/**
+ * Tests for default dashboard widget ordering.
+ *
+ * @package Presence_API
+ *
+ * @group presence
+ */
+class WP_Test_Presence_Dashboard_Widget_Order extends WP_UnitTestCase {
+
+	private static $admin_id;
+
+	public static function wpSetUpBeforeClass( WP_UnitTest_Factory $factory ) {
+		self::$admin_id = $factory->user->create( array( 'role' => 'administrator' ) );
+	}
+
+	/**
+	 * @covers ::wp_presence_default_widget_order
+	 */
+	public function test_returns_default_order_when_no_preference_set() {
+		$result = wp_presence_default_widget_order( false );
+
+		$this->assertIsArray( $result );
+		$this->assertStringStartsWith( 'presence_whos_online,presence_active_posts', $result['normal'] );
+	}
+
+	/**
+	 * @covers ::wp_presence_default_widget_order
+	 */
+	public function test_returns_existing_order_unchanged_when_preference_is_set() {
+		$custom = array(
+			'normal' => 'dashboard_activity,dashboard_right_now',
+			'side'   => 'dashboard_quick_press',
+		);
+
+		$result = wp_presence_default_widget_order( $custom );
+
+		$this->assertSame( $custom, $result );
+	}
+
+	/**
+	 * @covers ::wp_presence_default_widget_order
+	 */
+	public function test_filter_is_applied_via_get_user_option() {
+		wp_set_current_user( self::$admin_id );
+
+		$order = get_user_option( 'meta-box-order_dashboard', self::$admin_id );
+
+		$this->assertIsArray( $order );
+		$this->assertStringStartsWith( 'presence_whos_online,presence_active_posts', $order['normal'] );
+	}
+
+	/**
+	 * @covers ::wp_presence_default_widget_order
+	 */
+	public function test_filter_does_not_override_saved_preference() {
+		wp_set_current_user( self::$admin_id );
+		$custom = array( 'normal' => 'dashboard_right_now,dashboard_activity' );
+		update_user_option( self::$admin_id, 'meta-box-order_dashboard', $custom );
+
+		$order = get_user_option( 'meta-box-order_dashboard', self::$admin_id );
+
+		$this->assertSame( $custom, $order );
+
+		delete_user_option( self::$admin_id, 'meta-box-order_dashboard' );
+	}
+}