desktop-mode / includes / unfocus-effects.php

unfocus-effects.php in OpenStation: Desktop Windows, Dock & Virtual Desktops for WP Admin 0.9.1, at includes/unfocus-effects.php

157 lines 4.7 KB

Raw Download Zip

1	<?php
2	/**
3	* Desktop unfocused-window effect registration API.
4	*
5	* Mirrors the command-script / title-bar-button-script registration
6	* pattern: minimum-ceremony PHP opt-in
7	* (`desktop_mode_register_unfocus_effect_script`) tells the shell which
8	* enqueued scripts contribute unfocus effects. The shell injects the
9	* script URL into the live-refresh payload so a plugin activated
10	* mid-session surfaces its effect in OS Settings → Effects immediately,
11	* no F5 needed.
12	*
13	* Effects themselves are declared JS-side via
14	* `wp.desktop.registerUnfocusEffect( … )` — the CSS class, apply/clear
15	* callbacks, and label all live in the plugin's TypeScript /
16	* JavaScript. The built-in `darken` is registered through the very
17	* same JS hook (see `src/effects/registry.ts`).
18	*
19	* @since 0.26.0
20	* @package WPDesktopMode
21	*/
22
23	defined( 'ABSPATH' ) \|\| exit;
24
25	/**
26	* Declare a WP-registered script handle as an unfocus-effect provider.
27	*
28	* Example:
29	*
30	* ```php
31	* add_action( 'admin_enqueue_scripts', function () {
32	* wp_register_script(
33	* 'my-plugin-effects',
34	* plugins_url( 'js/effects.js', __FILE__ ),
35	* array( 'desktop-mode' ),
36	* '1.0.0',
37	* true
38	* );
39	* wp_enqueue_script( 'my-plugin-effects' );
40	* } );
41	* desktop_mode_register_unfocus_effect_script( 'my-plugin-effects' );
42	* ```
43	*
44	* For live unregistration on deactivation, the plugin's JS should set
45	* `owner: 'my-plugin-effects'` on each `registerUnfocusEffect` call.
46	* Otherwise the effect stays until the next page reload — graceful
47	* backwards-compat.
48	*
49	* @since 0.26.0
50	*
51	* @param string $handle WP-registered script handle.
52	* @return true\|WP_Error `true` on success; `WP_Error` on validation failure.
53	*/
54	function desktop_mode_register_unfocus_effect_script( $handle ) {
55	$handle = (string) $handle;
56	if ( '' === $handle ) {
57	return desktop_mode_registration_error(
58	'desktop_mode_missing_handle',
59	__( 'Unfocus effect script registration requires a non-empty script handle.', 'desktop-mode' )
60	);
61	}
62
63	desktop_mode_desktop_unfocus_effect_script_registry( $handle, true );
64
65	/**
66	* Fires after a desktop unfocus-effect script handle is registered.
67	*
68	* @since 0.26.0
69	*
70	* @param string $handle The registered script handle.
71	*/
72	do_action( 'desktop_mode_unfocus_effect_script_registered', $handle );
73
74	return true;
75	}
76
77	/**
78	* Internal module-level registry for unfocus-effect script handles.
79	*
80	* @since 0.26.0
81	* @internal
82	*
83	* @param string $handle Script handle to read or write.
84	* @param bool\|null $value Pass `true` to register; `null` to read only.
85	* @return array\|bool When called with no args returns the full store.
86	*/
87	function desktop_mode_desktop_unfocus_effect_script_registry( $handle = '', $value = null ) {
88	static $store = array();
89
90	if ( '__flush__' === (string) $handle ) {
91	$store = array();
92	return array();
93	}
94	if ( '' === (string) $handle ) {
95	return $store;
96	}
97	if ( null !== $value ) {
98	$store[ (string) $handle ] = (bool) $value;
99	}
100	return isset( $store[ (string) $handle ] ) ? $store[ (string) $handle ] : false;
101	}
102
103	/**
104	* Test-only: clear the registry between PHPUnit cases. See
105	* {@see desktop_mode_flush_script_handle_registries()}.
106	*
107	* @since 0.26.0
108	*/
109	function desktop_mode_flush_desktop_unfocus_effect_script_registry() {
110	desktop_mode_desktop_unfocus_effect_script_registry( '__flush__' );
111	}
112
113	/**
114	* Build the script-handle payload fed to the shell. Handles that
115	* aren't currently enqueued resolve to an empty URL and are dropped.
116	*
117	* @since 0.26.0
118	*
119	* @return array[] List of `{ handle, scriptUrl, … }` entries.
120	*/
121	function desktop_mode_build_desktop_unfocus_effect_scripts_payload() {
122	$registry = desktop_mode_desktop_unfocus_effect_script_registry();
123	if ( ! is_array( $registry ) \|\| empty( $registry ) ) {
124	return array();
125	}
126
127	$out = array();
128	$seen = array();
129	foreach ( $registry as $handle => $active ) {
130	if ( ! $active \|\| isset( $seen[ $handle ] ) ) {
131	continue;
132	}
133	$payload = desktop_mode_resolve_script_payload( $handle );
134	if ( '' === $payload['url'] ) {
135	// Loud diagnostic — visible under WP_DEBUG. Deduped by
136	// `desktop_mode_warn_unresolvable_script_handle` so the
137	// notice fires once per handle per request.
138	desktop_mode_warn_unresolvable_script_handle(
139	'desktop_mode_register_unfocus_effect_script',
140	'Unfocus effect',
141	(string) $handle
142	);
143	continue;
144	}
145	$out[] = array(
146	'handle' => (string) $handle,
147	'scriptUrl' => $payload['url'],
148	'scriptBefore' => $payload['before'],
149	'scriptAfter' => $payload['after'],
150	'scriptL10n' => $payload['l10n'],
151	'scriptTranslations' => $payload['translations'],
152	);
153	$seen[ $handle ] = true;
154	}
155	return $out;
156	}
157