← All changes | jetpack_vendor/automattic/jetpack-admin-ui/src/class-admin-menu.php +1026 -0 16.2-beta → 16.3-a.7 View file →

		@@ -1,0 +1,1026 @@
	1	+<?php
	2	+/**
	3	+ * Admin Menu Registration
	4	+ *
	5	+ * @package automattic/jetpack-admin-ui
	6	+ */
	7	+
	8	+namespace Automattic\Jetpack\Admin_UI;
	9	+
	10	+use Automattic\Jetpack\Feature_Policy;
	11	+use Automattic\Jetpack\Tracking;
	12	+use Jetpack_Options;
	13	+use Jetpack_Tracks_Client;
	14	+
	15	+/**
	16	+ * This class offers a wrapper to add_submenu_page and makes sure stand-alone plugin's menu items are always added under the Jetpack top level menu.
	17	+ * If the Jetpack top level was not previously registered by other plugin, it will be registered here.
	18	+ */
	19	+class Admin_Menu {
	20	+
	21	+ const PACKAGE_VERSION = '0.14.2';
	22	+
	23	+ /**
	24	+ * Slug used for the upgrade menu item and redirect URL.
	25	+ *
	26	+ * Keep the slug in sync with `$upgrade-menu-slug` at admin-ui-upgrade-menu.scss
	27	+ *
	28	+ * @var string
	29	+ */
	30	+ const UPGRADE_MENU_SLUG = 'jetpack-wpadmin-sidebar-free-plan-upsell-menu-item';
	31	+
	32	+ /**
	33	+ * Fallback upgrade URL when the Redirect class is unavailable.
	34	+ *
	35	+ * @var string
	36	+ */
	37	+ const UPGRADE_MENU_FALLBACK_URL = 'https://jetpack.com/upgrade/';
	38	+
	39	+ /*
	40	+ * The sidebar's position tiers. Items sharing a tier sort alphabetically by menu title, so a
	41	+ * product should pass no position and land in POSITION_DEFAULT. add_menu() treats any value
	42	+ * that is not a tier below as omitted, so an int of your own cannot opt an item out.
	43	+ */
	44	+
	45	+ /**
	46	+ * Owns the top-level Jetpack link, since WordPress points it at whichever item sorts first.
	47	+ *
	48	+ * @var int
	49	+ */
	50	+ const POSITION_FIRST = -10;
	51	+
	52	+ /**
	53	+ * Takes the first slot when nothing claims POSITION_FIRST, as in offline mode.
	54	+ *
	55	+ * @var int
	56	+ */
	57	+ const POSITION_FIRST_FALLBACK = -5;
	58	+
	59	+ /**
	60	+ * Products, in alphabetical order. Pass no position rather than this.
	61	+ *
	62	+ * @var int
	63	+ */
	64	+ const POSITION_DEFAULT = 0;
	65	+
	66	+ /**
	67	+ * Links that leave wp-admin, grouped below the products.
	68	+ *
	69	+ * @var int
	70	+ */
	71	+ const POSITION_EXTERNAL = 100;
	72	+
	73	+ /**
	74	+ * Site-level items that belong under everything else.
	75	+ *
	76	+ * @var int
	77	+ */
	78	+ const POSITION_LAST = 998;
	79	+
	80	+ /**
	81	+ * The upgrade item this package adds, below every tier a caller can use.
	82	+ *
	83	+ * @var int
	84	+ */
	85	+ const POSITION_UPGRADE = 999;
	86	+
	87	+ /**
	88	+ * The tiers add_menu() accepts. POSITION_UPGRADE is left out: only this class claims it.
	89	+ *
	90	+ * @var int[]
	91	+ */
	92	+ private const CALLER_POSITIONS = array(
	93	+ self::POSITION_FIRST,
	94	+ self::POSITION_FIRST_FALLBACK,
	95	+ self::POSITION_DEFAULT,
	96	+ self::POSITION_EXTERNAL,
	97	+ self::POSITION_LAST,
	98	+ );
	99	+
	100	+ /**
	101	+ * Handle for the bundled WPDS design-tokens stylesheet.
	102	+ *
	103	+ * Fallback when Core/Gutenberg has not registered the `wp-theme` style.
	104	+ *
	105	+ * @var string
	106	+ */
	107	+ const DESIGN_TOKENS_HANDLE = 'jetpack-admin-ui-design-tokens';
	108	+
	109	+ /**
	110	+ * Handle for the source-less stylesheet that hides WordPress core admin notices.
	111	+ *
	112	+ * @var string
	113	+ */
	114	+ const HIDE_CORE_NOTICES_HANDLE = 'jetpack-admin-ui-hide-core-notices';
	115	+
	116	+ /**
	117	+ * Visibility state: show the item only when its declared gate is satisfied.
	118	+ *
	119	+ * @var string
	120	+ */
	121	+ const VISIBILITY_DEFAULT = 'default';
	122	+
	123	+ /**
	124	+ * Visibility state: show the item whatever its gate says.
	125	+ *
	126	+ * @var string
	127	+ */
	128	+ const VISIBILITY_VISIBLE = 'visible';
	129	+
	130	+ /**
	131	+ * Visibility state: keep the item out whatever its gate says.
	132	+ *
	133	+ * @var string
	134	+ */
	135	+ const VISIBILITY_HIDDEN = 'hidden';
	136	+
	137	+ /**
	138	+ * Whether this class has been initialized
	139	+ *
	140	+ * @var boolean
	141	+ */
	142	+ private static $initialized = false;
	143	+
	144	+ /**
	145	+ * List of menu items enqueued to be added
	146	+ *
	147	+ * @var array
	148	+ */
	149	+ private static $menu_items = array();
	150	+
	151	+ /**
	152	+ * List of top level menu items enqueued to be added
	153	+ *
	154	+ * @var array
	155	+ */
	156	+ private static $top_level_items = array();
	157	+
	158	+ /**
	159	+ * Hook suffixes of the pages registered through this class.
	160	+ *
	161	+ * Used to scope the design-tokens stylesheet to Jetpack admin pages.
	162	+ *
	163	+ * @var array
	164	+ */
	165	+ private static $page_hooks = array();
	166	+
	167	+ /**
	168	+ * Optional connection manager dependency.
	169	+ *
	170	+ * @var object|null
	171	+ */
	172	+ private static $connection_manager = null;
	173	+
	174	+ /**
	175	+ * Callback that answers whether a menu item's declared gate is satisfied.
	176	+ *
	177	+ * Set by My Jetpack, which owns the product classes the gates name. Stays null on a
	178	+ * site without it, where every gate then fails open.
	179	+ *
	180	+ * @var callable|null
	181	+ */
	182	+ private static $visibility_resolver = null;
	183	+
	184	+ /**
	185	+ * Menu slugs registered this request but kept out of the rendered sidebar.
	186	+ *
	187	+ * @var string[]
	188	+ */
	189	+ private static $hidden_menu_slugs = array();
	190	+
	191	+ /**
	192	+ * Top level menu slugs registered this request but kept out of the rendered sidebar.
	193	+ *
	194	+ * @var string[]
	195	+ */
	196	+ private static $hidden_top_level_slugs = array();
	197	+
	198	+ /**
	199	+ * Whether the top level registration pass has been hooked.
	200	+ *
	201	+ * Separate from $initialized, which also builds the Jetpack menu.
	202	+ *
	203	+ * @var boolean
	204	+ */
	205	+ private static $top_level_initialized = false;
	206	+
	207	+ /**
	208	+ * Initialize the class and set up the main hook
	209	+ *
	210	+ * @return void
	211	+ */
	212	+ public static function init() {
	213	+ if ( ! self::$initialized ) {
	214	+ self::$initialized = true;
	215	+ self::handle_akismet_menu();
	216	+ add_action( 'admin_menu', array( __CLASS__, 'admin_menu_hook_callback' ), 1000 ); // Jetpack uses 998.
	217	+ add_action( 'network_admin_menu', array( __CLASS__, 'admin_menu_hook_callback' ), 1000 ); // Jetpack uses 998.
	218	+ add_action( 'admin_head', array( __CLASS__, 'remove_hidden_menu_items' ) );
	219	+ add_action( 'admin_enqueue_scripts', array( __CLASS__, 'add_upgrade_menu_item_styles' ) );
	220	+ add_action( 'admin_enqueue_scripts', array( __CLASS__, 'maybe_enqueue_design_tokens' ) );
	221	+ }
	222	+ }
	223	+
	224	+ /**
	225	+ * Drops every queued item and unhooks the registration passes.
	226	+ *
	227	+ * Intended for tests.
	228	+ *
	229	+ * @return void
	230	+ */
	231	+ public static function reset() {
	232	+ self::$menu_items = array();
	233	+ self::$top_level_items = array();
	234	+ self::$page_hooks = array();
	235	+ self::$hidden_menu_slugs = array();
	236	+ self::$hidden_top_level_slugs = array();
	237	+ self::$initialized = false;
	238	+ self::$top_level_initialized = false;
	239	+
	240	+ remove_action( 'admin_menu', array( __CLASS__, 'admin_menu_hook_callback' ), 1000 );
	241	+ remove_action( 'network_admin_menu', array( __CLASS__, 'admin_menu_hook_callback' ), 1000 );
	242	+ remove_action( 'admin_menu', array( __CLASS__, 'top_level_menu_hook_callback' ), 1000 );
	243	+ remove_action( 'admin_head', array( __CLASS__, 'remove_hidden_menu_items' ) );
	244	+ remove_action( 'admin_enqueue_scripts', array( __CLASS__, 'add_upgrade_menu_item_styles' ) );
	245	+ remove_action( 'admin_enqueue_scripts', array( __CLASS__, 'maybe_enqueue_design_tokens' ) );
	246	+ }
	247	+
	248	+ /**
	249	+ * Handles the Akismet menu item when used alongside other stand-alone plugins
	250	+ *
	251	+ * When Jetpack plugin is present, Akismet menu item is moved under the Jetpack top level menu, but if Akismet is active alongside other stand-alone plugins,
	252	+ * we use this method to move the menu item.
	253	+ */
	254	+ private static function handle_akismet_menu() {
	255	+ if ( class_exists( 'Akismet_Admin' ) ) {
	256	+ add_action(
	257	+ 'admin_menu',
	258	+ function () {
	259	+ // Prevent Akismet from adding a menu item.
	260	+ remove_action( 'admin_menu', array( 'Akismet_Admin', 'admin_menu' ), 5 );
	261	+
	262	+ // Add an Anti-spam menu item for Jetpack.
	263	+ self::add_menu( __( 'Akismet Anti-spam', 'jetpack-admin-ui' ), __( 'Akismet Anti-spam', 'jetpack-admin-ui' ), 'manage_options', 'akismet-key-config', array( 'Akismet_Admin', 'display_page' ) );
	264	+ },
	265	+ 4
	266	+ );
	267	+
	268	+ }
	269	+ }
	270	+
	271	+ /**
	272	+ * Callback to the admin_menu and network_admin_menu hooks that will register the enqueued menu items
	273	+ *
	274	+ * @return void
	275	+ */
	276	+ public static function admin_menu_hook_callback() {
	277	+ $can_see_toplevel_menu = true;
	278	+ $jetpack_plugin_present = class_exists( 'Jetpack_React_Page' );
	279	+ $icon = 'dashicons-admin-plugins';
	280	+ if ( method_exists( '\Automattic\Jetpack\Assets\Logo', 'get_base64_admin_menu_logo' ) ) {
	281	+ $icon = ( new \Automattic\Jetpack\Assets\Logo() )->get_base64_admin_menu_logo();
	282	+ } elseif ( method_exists( '\Automattic\Jetpack\Assets\Logo', 'get_base64_logo' ) ) {
	283	+ $icon = ( new \Automattic\Jetpack\Assets\Logo() )->get_base64_logo();
	284	+ }
	285	+
	286	+ if ( ! $jetpack_plugin_present ) {
	287	+ add_menu_page(
	288	+ 'Jetpack',
	289	+ 'Jetpack',
	290	+ 'edit_posts',
	291	+ 'jetpack',
	292	+ '__return_null',
	293	+ $icon,
	294	+ 3
	295	+ );
	296	+
	297	+ // If Jetpack plugin is not present, user will only be able to see this menu if they have enough capability to at least one of the sub menus being added.
	298	+ $can_see_toplevel_menu = false;
	299	+ }
	300	+
	301	+ /*
	302	+ * Sort here and register in that order, without passing the position on: core splices an
	303	+ * int back in, and prepends 0 or less. See https://core.trac.wordpress.org/ticket/52035.
	304	+ */
	305	+ usort(
	306	+ self::$menu_items,
	307	+ function ( $a, $b ) {
	308	+ $position_a = empty( $a['position'] ) ? 0 : $a['position'];
	309	+ $position_b = empty( $b['position'] ) ? 0 : $b['position'];
	310	+ $result = $position_a <=> $position_b;
	311	+
	312	+ if ( 0 === $result ) {
	313	+ // Case-insensitive and number-aware, so "eCommerce" sorts with the Es.
	314	+ // Still a byte compare: a leading accented character sorts after Z.
	315	+ $result = strnatcasecmp( $a['menu_title'], $b['menu_title'] );
	316	+ }
	317	+
	318	+ return $result;
	319	+ }
	320	+ );
	321	+
	322	+ $visibility = self::get_visibility_states();
	323	+
	324	+ self::$hidden_menu_slugs = array();
	325	+
	326	+ foreach ( self::$menu_items as $menu_item ) {
	327	+ if ( ! current_user_can( $menu_item['capability'] ) ) {
	328	+ continue;
	329	+ }
	330	+
	331	+ /*
	332	+ * A hidden item is still registered, so its page keeps resolving for links into it.
	333	+ * It leaves the submenu on admin_head instead: core's access check reads $submenu.
	334	+ */
	335	+ if ( self::is_menu_item_visible( $menu_item, $visibility ) ) {
	336	+ $can_see_toplevel_menu = true;
	337	+ } else {
	338	+ self::$hidden_menu_slugs[] = $menu_item['menu_slug'];
	339	+ }
	340	+
	341	+ add_submenu_page(
	342	+ 'jetpack',
	343	+ $menu_item['page_title'],
	344	+ $menu_item['menu_title'],
	345	+ $menu_item['capability'],
	346	+ $menu_item['menu_slug'],
	347	+ $menu_item['function']
	348	+ );
	349	+ }
	350	+
	351	+ if ( ! $jetpack_plugin_present ) {
	352	+ remove_submenu_page( 'jetpack', 'jetpack' );
	353	+ }
	354	+
	355	+ if ( ! $can_see_toplevel_menu ) {
	356	+ remove_menu_page( 'jetpack' );
	357	+ }
	358	+
	359	+ self::maybe_add_upgrade_menu_item();
	360	+ }
	361	+
	362	+ /**
	363	+ * Hooks the top level registration pass, without building the Jetpack menu that init() does.
	364	+ *
	365	+ * @return void
	366	+ */
	367	+ private static function init_top_level() {
	368	+ if ( ! self::$top_level_initialized ) {
	369	+ self::$top_level_initialized = true;
	370	+ add_action( 'admin_menu', array( __CLASS__, 'top_level_menu_hook_callback' ), 1000 );
	371	+ add_action( 'admin_head', array( __CLASS__, 'remove_hidden_menu_items' ) );
	372	+ }
	373	+ }
	374	+
	375	+ /**
	376	+ * Registers the queued top level items, skipping the ones that should not be seen.
	377	+ *
	378	+ * These sit beside the Jetpack menu, so they never count towards keeping it alive.
	379	+ *
	380	+ * @return void
	381	+ */
	382	+ public static function top_level_menu_hook_callback() {
	383	+ $visibility = self::get_visibility_states();
	384	+
	385	+ self::$hidden_top_level_slugs = array();
	386	+
	387	+ foreach ( self::$top_level_items as $menu_item ) {
	388	+ if ( ! current_user_can( $menu_item['capability'] ) ) {
	389	+ continue;
	390	+ }
	391	+
	392	+ if ( ! self::is_menu_item_visible( $menu_item, $visibility ) ) {
	393	+ self::$hidden_top_level_slugs[] = $menu_item['menu_slug'];
	394	+ }
	395	+
	396	+ add_menu_page(
	397	+ $menu_item['page_title'],
	398	+ $menu_item['menu_title'],
	399	+ $menu_item['capability'],
	400	+ $menu_item['menu_slug'],
	401	+ $menu_item['function'],
	402	+ $menu_item['icon_url'],
	403	+ $menu_item['position']
	404	+ );
	405	+ }
	406	+ }
	407	+
	408	+ /**
	409	+ * Adds a top level menu item under the same visibility gate and filter as add_menu().
	410	+ *
	411	+ * Unlike add_menu(), the page gets neither the core-notice CSS nor the design tokens.
	412	+ * Parameters mirror add_menu_page(), with $args appended.
	413	+ *
	414	+ * @since 0.13.0
	415	+ *
	416	+ * @param string $page_title The text to be displayed in the title tags of the page when the menu
	417	+ * is selected.
	418	+ * @param string $menu_title The text to be used for the menu.
	419	+ * @param string $capability The capability required for this menu to be displayed to the user.
	420	+ * @param string $menu_slug The slug name to refer to this menu by. Should be unique for this menu.
	421	+ * @param callable|null $function The function to be called to output the content for this page.
	422	+ * @param string $icon_url The URL to the icon to be used for this menu, or a dashicons class.
	423	+ * @param int|null $position The position in the menu order this item should appear.
	424	+ * @param array $args Optional. Visibility declaration for this item; see add_menu().
	425	+ *
	426	+ * @return string The resulting page's hook_suffix
	427	+ */
	428	+ public static function add_top_level_menu( $page_title, $menu_title, $capability, $menu_slug, $function, $icon_url = '', $position = null, $args = array() ) {
	429	+ self::init_top_level();
	430	+ self::$top_level_items[] = compact( 'page_title', 'menu_title', 'capability', 'menu_slug', 'function', 'icon_url', 'position', 'args' );
	431	+
	432	+ // Same derivation as get_plugin_page_hookname(), which strips ".php" anywhere in the slug.
	433	+ return 'toplevel_page_' . preg_replace( '!\.php!', '', plugin_basename( $menu_slug ) );
	434	+ }
	435	+
	436	+ /**
	437	+ * Adds a new submenu to the Jetpack Top level menu
	438	+ *
	439	+ * The parameters this method accepts are the same as @see add_submenu_page. This class will
	440	+ * aggreagate all menu items registered by stand-alone plugins and make sure they all go under the same
	441	+ * Jetpack top level menu. It will also handle the top level menu registration in case the Jetpack plugin is not present.
	442	+ *
	443	+ * @param string $page_title The text to be displayed in the title tags of the page when the menu
	444	+ * is selected.
	445	+ * @param string $menu_title The text to be used for the menu.
	446	+ * @param string $capability The capability required for this menu to be displayed to the user.
	447	+ * @param string $menu_slug The slug name to refer to this menu by. Should be unique for this menu
	448	+ * and only include lowercase alphanumeric, dashes, and underscores characters
	449	+ * to be compatible with sanitize_key().
	450	+ * @param callable|null $function The function to be called to output the content for this page.
	451	+ * @param int|null $position One of the POSITION_* tiers; any other value is ignored. Leave empty typically.
	452	+ * @param array $args Optional. Visibility declaration for this item:
	453	+ * - 'product' (string) My Jetpack product slug whose activation gates the item.
	454	+ * - 'module' (string) Jetpack module name, for items with no product class.
	455	+ * - 'key' (string) The name hosts use for this item in the visibility
	456	+ * filter. Declare one on every item; see get_item_key().
	457	+ * An item that declares no gate is always shown.
	458	+ *
	459	+ * @return string The resulting page's hook_suffix
	460	+ */
	461	+ public static function add_menu( $page_title, $menu_title, $capability, $menu_slug, $function, $position = null, $args = array() ) {
	462	+ self::init();
	463	+
	464	+ /*
	465	+ * Anything but a tier would opt the item out of the alphabetical order, so treat it as omitted.
	466	+ * @todo Add _doing_it_wrong() here after December 2026. Until all our own plugins ship tier-only
	467	+ * positions, it would have the latest release of one Jetpack plugin warning about another.
	468	+ */
	469	+ $position = is_numeric( $position ) && in_array( (int) $position, self::CALLER_POSITIONS, true ) ? (int) $position : null;
	470	+
	471	+ self::$menu_items[] = compact( 'page_title', 'menu_title', 'capability', 'menu_slug', 'function', 'position', 'args' );
	472	+
	473	+ /**
	474	+ * Let's return the page hook so consumers can use.
	475	+ * We know all pages will be under Jetpack top level menu page, so we can hardcode the first part of the string.
	476	+ * Using get_plugin_page_hookname here won't work because the top level page is not registered yet.
	477	+ */
	478	+ $hook = 'jetpack_page_' . $menu_slug;
	479	+
	480	+ // Track the page hook so the design-tokens stylesheet can be scoped to it.
	481	+ self::$page_hooks[] = $hook;
	482	+
	483	+ // Hide WordPress core admin notices on this Jetpack page. The load-<hook>
	484	+ // action only fires when the matching screen is being rendered, so this
	485	+ // stays scoped to Jetpack pages and reaches every page registered here.
	486	+ add_action( 'load-' . $hook, array( __CLASS__, 'hide_core_admin_notices' ) );
	487	+ add_action( 'load-' . $hook . '-network', array( __CLASS__, 'hide_core_admin_notices' ) );
	488	+
	489	+ return $hook;
	490	+ }
	491	+
	492	+ /**
	493	+ * Enqueues the stylesheet that hides WordPress core admin notices on the current Jetpack page.
	494	+ *
	495	+ * Hooked from the page's load-<hook> action so it only runs on Jetpack screens. That action
	496	+ * runs before admin_enqueue_scripts, so the handle is queued in time to be printed.
	497	+ *
	498	+ * @return void
	499	+ */
	500	+ public static function hide_core_admin_notices() {
	501	+ // wp_add_inline_style() appends, so the CSS is attached only while the handle is new to the request.
	502	+ if ( ! wp_style_is( self::HIDE_CORE_NOTICES_HANDLE, 'registered' ) ) {
	503	+ wp_register_style( self::HIDE_CORE_NOTICES_HANDLE, false, array(), self::PACKAGE_VERSION );
	504	+ wp_add_inline_style( self::HIDE_CORE_NOTICES_HANDLE, self::get_hide_core_admin_notices_styles() );
	505	+ }
	506	+
	507	+ wp_enqueue_style( self::HIDE_CORE_NOTICES_HANDLE );
	508	+ }
	509	+
	510	+ /**
	511	+ * Enqueues the CSS that hides WordPress core admin notices.
	512	+ *
	513	+ * Callers must run this before WordPress flushes the style queue in
	514	+ * print_admin_styles() (admin_print_styles, priority 20). Later than that,
	515	+ * the handle is never printed. The previous admin_print_styles priority-10
	516	+ * hook still works.
	517	+ *
	518	+ * @deprecated 0.10.0 Use hide_core_admin_notices(), which enqueues the CSS.
	519	+ *
	520	+ * @return void
	521	+ */
	522	+ public static function print_hide_core_admin_notices_style() {
	523	+ _deprecated_function( __METHOD__, 'admin-ui-0.10.0', __CLASS__ . '::hide_core_admin_notices' );
	524	+ self::hide_core_admin_notices();
	525	+ }
	526	+
	527	+ /**
	528	+ * Gets the CSS that hides WordPress core admin notices.
	529	+ *
	530	+ * We only target direct children of #wpbody-content (where core renders notices via the
	531	+ * admin_notices / all_admin_notices hooks). This intentionally leaves JITMs untouched —
	532	+ * they output `.jetpack-jitm-message`, not `.notice` — and leaves in-app/React notices
	533	+ * untouched, since those render deeper inside `.wrap`. The CSS rides on a source-less
	534	+ * handle rather than a build asset so it also reaches older Jetpack pages that ship no
	535	+ * stylesheet of their own.
	536	+ *
	537	+ * @return string CSS rules.
	538	+ */
	539	+ private static function get_hide_core_admin_notices_styles() {
	540	+ return '
	541	+ #wpbody-content > .notice,
	542	+ #wpbody-content > .update-nag,
	543	+ #wpbody-content > .updated,
	544	+ #wpbody-content > .error { display: none !important; }
	545	+ ';
	546	+ }
	547	+
	548	+ /**
	549	+ * Sets the callback that resolves a menu item's declared gate.
	550	+ *
	551	+ * The callback receives the item's $args array and returns true (gate satisfied),
	552	+ * false (not satisfied), or null when it cannot answer — an unknown product slug,
	553	+ * for instance. Null is treated as satisfied, so a gate this package cannot resolve
	554	+ * never removes a menu item.
	555	+ *
	556	+ * This is the seam My Jetpack fills. Hosts wanting to shape the sidebar should use the
	557	+ * `jetpack_admin_menu_visibility` filter instead, which takes precedence: an item the
	558	+ * filter names is never put to this callback at all.
	559	+ *
	560	+ * @param callable|null $resolver Resolver callback, or null to clear it.
	561	+ * @return void
	562	+ */
	563	+ public static function set_visibility_resolver( $resolver ) {
	564	+ self::$visibility_resolver = $resolver;
	565	+ }
	566	+
	567	+ /**
	568	+ * Takes hidden items out of the sidebar before it renders.
	569	+ *
	570	+ * Runs on admin_head, after core's access check has already resolved the current page,
	571	+ * so a hidden item's page stays reachable while its entry disappears.
	572	+ *
	573	+ * @return void
	574	+ */
	575	+ public static function remove_hidden_menu_items() {
	576	+ foreach ( self::$hidden_menu_slugs as $menu_slug ) {
	577	+ remove_submenu_page( 'jetpack', plugin_basename( $menu_slug ) );
	578	+ }
	579	+
	580	+ foreach ( self::$hidden_top_level_slugs as $menu_slug ) {
	581	+ remove_menu_page( plugin_basename( $menu_slug ) );
	582	+ }
	583	+ }
	584	+
	585	+ /**
	586	+ * Returns the name a host uses for a menu item in the visibility filter.
	587	+ *
	588	+ * The menu slug is only a fallback. It is the wrong thing to hand a host as an identifier:
	589	+ * several items register a URL as their slug, Blaze's is filterable, and VideoPress swaps
	590	+ * between two slugs depending on whether the module is active — so a host naming one of
	591	+ * them is naming a moving target, or only half an item.
	592	+ *
	593	+ * @param array $menu_item A registered menu item.
	594	+ * @return string
	595	+ */
	596	+ private static function get_item_key( array $menu_item ) {
	597	+ if ( ! empty( $menu_item['args']['key'] ) ) {
	598	+ return (string) $menu_item['args']['key'];
	599	+ }
	600	+
	601	+ return (string) $menu_item['menu_slug'];
	602	+ }
	603	+
	604	+ /**
	605	+ * Builds the item => state map and hands it to hosts to amend.
	606	+ *
	607	+ * @return array Map of item key to one of the VISIBILITY_* states.
	608	+ */
	609	+ private static function get_visibility_states() {
	610	+ // This filter is one a policy feeds, and nothing else need have read the policy this request.
	611	+ if ( method_exists( Feature_Policy::class, 'ensure_hooks' ) ) {
	612	+ Feature_Policy::ensure_hooks();
	613	+ }
	614	+
	615	+ $states = array();
	616	+ $items = array_merge( self::$menu_items, self::$top_level_items );
	617	+
	618	+ foreach ( $items as $menu_item ) {
	619	+ $states[ self::get_item_key( $menu_item ) ] = self::VISIBILITY_DEFAULT;
	620	+ }
	621	+
	622	+ /**
	623	+ * Filters which Jetpack items appear in the wp-admin sidebar.
	624	+ *
	625	+ * Governs the sidebar entry only — a hidden item's page stays reachable by URL, so this
	626	+ * is not an access control. States: 'default' follows the item's feature, 'visible' shows it, 'hidden' removes it.
	627	+ *
	628	+ * @since 0.12.0
	629	+ *
	630	+ * @param array $states Map of item key (menu slug unless the item declared one) to state.
	631	+ * @param array $menu_items The registered menu items, for context.
	632	+ */
	633	+ $states = apply_filters( 'jetpack_admin_menu_visibility', $states, $items );
	634	+
	635	+ return is_array( $states ) ? $states : array();
	636	+ }
	637	+
	638	+ /**
	639	+ * Decides whether a single menu item should appear in the sidebar.
	640	+ *
	641	+ * @param array $menu_item A registered menu item.
	642	+ * @param array $visibility The resolved state map from get_visibility_states().
	643	+ * @return bool
	644	+ */
	645	+ private static function is_menu_item_visible( array $menu_item, array $visibility ) {
	646	+ $key = self::get_item_key( $menu_item );
	647	+ $state = $visibility[ $key ] ?? self::VISIBILITY_DEFAULT;
	648	+
	649	+ if ( self::VISIBILITY_HIDDEN === $state ) {
	650	+ return false;
	651	+ }
	652	+
	653	+ if ( self::VISIBILITY_VISIBLE === $state ) {
	654	+ return true;
	655	+ }
	656	+
	657	+ return self::is_gate_satisfied( $menu_item['args'] ?? array() );
	658	+ }
	659	+
	660	+ /**
	661	+ * Asks the resolver whether an item's declared gate is satisfied.
	662	+ *
	663	+ * Everything here fails open. An item that declares no gate, a site with no resolver
	664	+ * registered, and a gate the resolver does not recognize all keep the item in the
	665	+ * sidebar, so adopting this mechanism cannot remove an item nobody asked it to.
	666	+ *
	667	+ * @param array $args The item's visibility declaration.
	668	+ * @return bool
	669	+ */
	670	+ private static function is_gate_satisfied( array $args ) {
	671	+ if ( ! isset( $args['product'] ) && ! isset( $args['module'] ) ) {
	672	+ return true;
	673	+ }
	674	+
	675	+ if ( ! is_callable( self::$visibility_resolver ) ) {
	676	+ return true;
	677	+ }
	678	+
	679	+ $resolved = call_user_func( self::$visibility_resolver, $args );
	680	+
	681	+ return null === $resolved ? true : (bool) $resolved;
	682	+ }
	683	+
	684	+ /**
	685	+ * Removes an already added submenu
	686	+ *
	687	+ * @param string $menu_slug The slug of the submenu to remove.
	688	+ *
	689	+ * @return array|false The removed submenu on success, false if not found.
	690	+ */
	691	+ public static function remove_menu( $menu_slug ) {
	692	+
	693	+ foreach ( self::$menu_items as $index => $menu_item ) {
	694	+ if ( $menu_item['menu_slug'] === $menu_slug ) {
	695	+ unset( self::$menu_items[ $index ] );
	696	+
	697	+ return $menu_item;
	698	+ }
	699	+ }
	700	+
	701	+ return false;
	702	+ }
	703	+
	704	+ /**
	705	+ * Gets the slug for the first item under the Jetpack top level menu
	706	+ *
	707	+ * Skips hidden items rather than reading $submenu alone, because callers on admin_enqueue_scripts
	708	+ * and outside wp-admin ask before — or without — the admin_head pass that drops them.
	709	+ *
	710	+ * @return string|null
	711	+ */
	712	+ public static function get_top_level_menu_item_slug() {
	713	+ global $submenu;
	714	+
	715	+ if ( empty( $submenu['jetpack'] ) ) {
	716	+ return null;
	717	+ }
	718	+
	719	+ $hidden = array_map( 'plugin_basename', self::$hidden_menu_slugs );
	720	+
	721	+ foreach ( $submenu['jetpack'] as $item ) {
	722	+ if ( isset( $item[2] ) && ! in_array( $item[2], $hidden, true ) ) {
	723	+ return $item[2];
	724	+ }
	725	+ }
	726	+
	727	+ return null;
	728	+ }
	729	+
	730	+ /**
	731	+ * Gets the URL for the first item under the Jetpack top level menu
	732	+ *
	733	+ * @param string $fallback If Jetpack menu is not there or no children is found, return this fallback instead. Default to admin_url().
	734	+ * @return string
	735	+ */
	736	+ public static function get_top_level_menu_item_url( $fallback = false ) {
	737	+ $slug = self::get_top_level_menu_item_slug();
	738	+
	739	+ if ( $slug ) {
	740	+ $url = menu_page_url( $slug, false );
	741	+ return $url;
	742	+ }
	743	+
	744	+ $url = $fallback ? $fallback : admin_url();
	745	+ return $url;
	746	+ }
	747	+
	748	+ /**
	749	+ * Checks whether the current site should show the upgrade menu item.
	750	+ *
	751	+ * The upgrade menu is only shown to administrators on free-plan sites
	752	+ * that are not hosted on WordPress.com.
	753	+ *
	754	+ * @return bool True if the upgrade menu should be shown.
	755	+ */
	756	+ private static function should_show_upgrade_menu() {
	757	+
	758	+ // Only show to administrators.
	759	+ if ( ! current_user_can( 'manage_options' ) ) {
	760	+ return false;
	761	+ }
	762	+
	763	+ // Don't show upsells on WordPress.com platform.
	764	+ if ( class_exists( '\Automattic\Jetpack\Status\Host' ) ) {
	765	+ $host = new \Automattic\Jetpack\Status\Host();
	766	+ if ( $host->is_wpcom_platform() ) {
	767	+ return false;
	768	+ }
	769	+ }
	770	+
	771	+ // Don't show upsells in offline/development mode.
	772	+ if ( class_exists( '\Automattic\Jetpack\Status' ) ) {
	773	+ $status = new \Automattic\Jetpack\Status();
	774	+ if ( $status->is_offline_mode() ) {
	775	+ return false;
	776	+ }
	777	+ }
	778	+
	779	+ // Only show after the site and current user are connected.
	780	+ if ( ! self::is_site_and_user_connected() ) {
	781	+ return false;
	782	+ }
	783	+
	784	+ // Only show to free-plan sites.
	785	+ return self::is_free_plan();
	786	+ }
	787	+
	788	+ /**
	789	+ * Checks whether the site and current user are connected to WordPress.com.
	790	+ *
	791	+ * @return bool True if site and current user are connected.
	792	+ */
	793	+ private static function is_site_and_user_connected() {
	794	+ $connection_manager = self::$connection_manager;
	795	+ if ( ! $connection_manager && class_exists( '\Automattic\Jetpack\Connection\Manager' ) ) {
	796	+ $connection_manager = new \Automattic\Jetpack\Connection\Manager();
	797	+ self::$connection_manager = $connection_manager;
	798	+ }
	799	+
	800	+ if (
	801	+ $connection_manager
	802	+ && is_callable( array( $connection_manager, 'is_connected' ) )
	803	+ && is_callable( array( $connection_manager, 'is_user_connected' ) )
	804	+ ) {
	805	+ return (bool) $connection_manager->is_connected()
	806	+ && (bool) $connection_manager->is_user_connected( get_current_user_id() );
	807	+ }
	808	+
	809	+ return false;
	810	+ }
	811	+
	812	+ /**
	813	+ * Sets the connection manager dependency; used by tests.
	814	+ *
	815	+ * @param object|null $connection_manager Connection manager object.
	816	+ * @return void
	817	+ */
	818	+ public static function set_connection_manager( $connection_manager ) {
	819	+ self::$connection_manager = $connection_manager;
	820	+ }
	821	+
	822	+ /**
	823	+ * Checks whether the current site is on a free Jetpack plan with no active paid license.
	824	+ *
	825	+ * @return bool True if the site has no paid plan.
	826	+ */
	827	+ private static function is_free_plan() {
	828	+ // Check the active plan - use the is_free field or product_slug.
	829	+ $plan = get_option( 'jetpack_active_plan', array() );
	830	+
	831	+ // Back-compat: older plan payloads use class to indicate paid plans.
	832	+ if ( isset( $plan['class'] ) && 'free' !== $plan['class'] ) {
	833	+ return false;
	834	+ }
	835	+
	836	+ // If the plan explicitly says it's not free, trust that.
	837	+ if ( isset( $plan['is_free'] ) && false === $plan['is_free'] ) {
	838	+ return false;
	839	+ }
	840	+
	841	+ // Check if the product slug indicates a paid plan.
	842	+ if ( isset( $plan['product_slug'] ) && 'jetpack_free' !== $plan['product_slug'] ) {
	843	+ return false;
	844	+ }
	845	+
	846	+ // Also check for site products (licenses can add products without changing plan).
	847	+ $products = get_option( 'jetpack_site_products', array() );
	848	+ if ( ! empty( $products ) && is_array( $products ) ) {
	849	+ return false;
	850	+ }
	851	+
	852	+ return true;
	853	+ }
	854	+
	855	+ /**
	856	+ * Conditionally adds an "Upgrade Jetpack" submenu item for free-plan sites.
	857	+ *
	858	+ * Only shown to users with manage_options capability on self-hosted sites without a paid Jetpack plan or license.
	859	+ *
	860	+ * @return void
	861	+ */
	862	+ private static function maybe_add_upgrade_menu_item() {
	863	+ if ( ! self::should_show_upgrade_menu() ) {
	864	+ return;
	865	+ }
	866	+
	867	+ $upgrade_url = class_exists( '\Automattic\Jetpack\Redirect' )
	868	+ ? \Automattic\Jetpack\Redirect::get_url( self::UPGRADE_MENU_SLUG )
	869	+ : self::UPGRADE_MENU_FALLBACK_URL;
	870	+
	871	+ $menu_title = esc_html__( 'Upgrade Jetpack', 'jetpack-admin-ui' );
	872	+
	873	+ add_submenu_page(
	874	+ 'jetpack',
	875	+ $menu_title,
	876	+ $menu_title,
	877	+ 'manage_options',
	878	+ esc_url( $upgrade_url ),
	879	+ null, // @phan-suppress-current-line PhanTypeMismatchArgumentProbablyReal -- Core should ideally document null for no-callback arg. https://core.trac.wordpress.org/ticket/52539.
	880	+ self::POSITION_UPGRADE
	881	+ );
	882	+
	883	+ // Add a CSS class to the <li> element so styles can target it precisely.
	884	+ global $submenu;
	885	+ if ( ! empty( $submenu['jetpack'] ) ) {
	886	+ foreach ( $submenu['jetpack'] as $index => $item ) {
	887	+ if ( isset( $item[2] ) && false !== strpos( $item[2], self::UPGRADE_MENU_SLUG ) ) {
	888	+ // phpcs:ignore WordPress.WP.GlobalVariablesOverride.Prohibited
	889	+ $submenu['jetpack'][ $index ][4] = ( ! empty( $item[4] ) ? $item[4] . ' ' : '' ) . self::UPGRADE_MENU_SLUG;
	890	+ break;
	891	+ }
	892	+ }
	893	+ }
	894	+ }
	895	+
	896	+ /**
	897	+ * Enqueues admin styles for the "Upgrade Jetpack" menu item.
	898	+ *
	899	+ * The sidebar menu is visible on every admin page, so styles load globally.
	900	+ * Only enqueues for free-plan sites on self-hosted installs.
	901	+ *
	902	+ * @return void
	903	+ */
	904	+ public static function add_upgrade_menu_item_styles() {
	905	+ if ( ! self::should_show_upgrade_menu() ) {
	906	+ return;
	907	+ }
	908	+
	909	+ $asset_file = dirname( __DIR__ ) . '/build/admin-ui-upgrade-menu.asset.php';
	910	+ $asset = file_exists( $asset_file ) ? require $asset_file : array();
	911	+
	912	+ wp_enqueue_style(
	913	+ 'jetpack-admin-ui-upgrade-menu',
	914	+ plugins_url( '../build/admin-ui-upgrade-menu.css', __FILE__ ),
	915	+ $asset['dependencies'] ?? array(),
	916	+ $asset['version'] ?? self::PACKAGE_VERSION
	917	+ );
	918	+
	919	+ self::enqueue_upgrade_menu_tracks_script( $asset );
	920	+ }
	921	+
	922	+ /**
	923	+ * Enqueues WPDS design tokens so `var(--wpds-*)` values resolve at runtime.
	924	+ *
	925	+ * Prefer Core/Gutenberg's `wp-theme` style when registered; otherwise ship
	926	+ * the bundled copy. The caller scopes the call to the right page(s).
	927	+ *
	928	+ * @return void
	929	+ */
	930	+ public static function enqueue_design_tokens() {
	931	+ // Registered since WP 7.1 (and by Gutenberg):
	932	+ // https://make.wordpress.org/core/2026/07/31/design-system-theming-in-wordpress-7-1/
	933	+ if ( wp_style_is( 'wp-theme', 'registered' ) ) {
	934	+ wp_enqueue_style( 'wp-theme' );
	935	+ return;
	936	+ }
	937	+
	938	+ // @todo Remove this, the called function, and the webpack entrypoint it registers when WP 7.1 is the minimum version.
	939	+ self::register_design_tokens_style();
	940	+ wp_enqueue_style( self::DESIGN_TOKENS_HANDLE );
	941	+ }
	942	+
	943	+ /**
	944	+ * Registers the bundled, token-only WPDS design-tokens stylesheet.
	945	+ *
	946	+ * Used only when `wp-theme` is not registered. Safe to call repeatedly:
	947	+ * wp_register_style() is a no-op once the handle is registered.
	948	+ *
	949	+ * @return void
	950	+ */
	951	+ private static function register_design_tokens_style() {
	952	+ if ( wp_style_is( self::DESIGN_TOKENS_HANDLE, 'registered' ) ) {
	953	+ return;
	954	+ }
	955	+
	956	+ $asset_file = dirname( __DIR__ ) . '/build/design-tokens.asset.php';
	957	+ $asset = file_exists( $asset_file ) ? require $asset_file : array();
	958	+
	959	+ wp_register_style(
	960	+ self::DESIGN_TOKENS_HANDLE,
	961	+ plugins_url( '../build/design-tokens.css', __FILE__ ),
	962	+ $asset['dependencies'] ?? array(),
	963	+ $asset['version'] ?? self::PACKAGE_VERSION
	964	+ );
	965	+ }
	966	+
	967	+ /**
	968	+ * Enqueues the design tokens on the pages registered through this class.
	969	+ *
	970	+ * This is the admin_enqueue_scripts callback for the modernized Jetpack
	971	+ * dashboards. Scoped to self::$page_hooks so the tokens load wherever a
	972	+ * modernized dashboard renders, regardless of plan or connection state; the
	973	+ * actual enqueue is delegated to the reusable enqueue_design_tokens() API.
	974	+ *
	975	+ * @param string $hook_suffix The current admin page's hook suffix.
	976	+ * @return void
	977	+ */
	978	+ public static function maybe_enqueue_design_tokens( $hook_suffix ) {
	979	+ if ( ! in_array( $hook_suffix, self::$page_hooks, true ) ) {
	980	+ return;
	981	+ }
	982	+
	983	+ self::enqueue_design_tokens();
	984	+ }
	985	+
	986	+ /**
	987	+ * Enqueues Tracks for the upgrade submenu item.
	988	+ *
	989	+ * @param array $asset Parsed contents of admin-ui-upgrade-menu.asset.php.
	990	+ * @return void
	991	+ */
	992	+ private static function enqueue_upgrade_menu_tracks_script( $asset ) {
	993	+ if ( ! class_exists( '\Automattic\Jetpack\Tracking' ) ) {
	994	+ return;
	995	+ }
	996	+
	997	+ Tracking::register_tracks_functions_scripts( true );
	998	+
	999	+ wp_enqueue_script(
	1000	+ 'jetpack-admin-ui-upgrade-menu-tracking',
	1001	+ plugins_url( '../build/admin-ui-upgrade-menu-tracking.js', __FILE__ ),
	1002	+ $asset['dependencies'] ?? array(),
	1003	+ $asset['version'] ?? self::PACKAGE_VERSION,
	1004	+ true
	1005	+ );
	1006	+
	1007	+ $current_screen = get_current_screen();
	1008	+ $is_admin = current_user_can( 'jetpack_disconnect' );
	1009	+ $site_id = class_exists( 'Jetpack_Options' ) ? Jetpack_Options::get_option( 'id' ) : null;
	1010	+ $tracks_user_data = class_exists( 'Jetpack_Tracks_Client' ) ? Jetpack_Tracks_Client::get_connected_user_tracks_identity() : null;
	1011	+
	1012	+ wp_localize_script(
	1013	+ 'jetpack-admin-ui-upgrade-menu-tracking',
	1014	+ 'jetpackAdminUiUpgradeMenu',
	1015	+ array(
	1016	+ 'menuItemClass' => self::UPGRADE_MENU_SLUG,
	1017	+ 'tracksUserData' => $tracks_user_data,
	1018	+ 'tracksEventData' => array(
	1019	+ 'is_admin' => $is_admin,
	1020	+ 'current_screen' => $current_screen ? $current_screen->id : false,
	1021	+ 'blog_id' => $site_id,
	1022	+ ),
	1023	+ )
	1024	+ );
	1025	+ }
	1026	+}