desktop-mode / includes / unfocus-effects.php

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

147 lines 4.6 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	* (`openstation_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.os.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	* @package OpenStation
20	*/
21
22	defined( 'ABSPATH' ) \|\| exit;
23
24	/**
25	* Declare a WP-registered script handle as an unfocus-effect provider.
26	*
27	* Example:
28	*
29	* ```php
30	* add_action( 'admin_enqueue_scripts', function () {
31	* wp_register_script(
32	* 'my-plugin-effects',
33	* plugins_url( 'js/effects.js', __FILE__ ),
34	* array( 'openstation' ),
35	* '1.0.0',
36	* true
37	* );
38	* wp_enqueue_script( 'my-plugin-effects' );
39	* }, 5 ); // Before the shell harvests the payload at priority 10.
40	* openstation_register_unfocus_effect_script( 'my-plugin-effects' );
41	* ```
42	*
43	* For live unregistration on deactivation, the plugin's JS should set
44	* `owner: 'my-plugin-effects'` on each `registerUnfocusEffect` call.
45	* Otherwise the effect stays until the next page reload — graceful
46	* backwards-compat.
47	*
48	* @param string $handle WP-registered script handle.
49	* @return true\|WP_Error `true` on success; `WP_Error` on validation failure.
50	*/
51	function openstation_register_unfocus_effect_script( $handle ) {
52	$handle = (string) $handle;
53	if ( '' === $handle ) {
54	return openstation_registration_error(
55	'openstation_missing_handle',
56	__( 'Unfocus effect script registration requires a non-empty script handle.', 'desktop-mode' )
57	);
58	}
59
60	openstation_desktop_unfocus_effect_script_registry( $handle, true );
61
62	/**
63	* Fires after a desktop unfocus-effect script handle is registered.
64	*
65	* @param string $handle The registered script handle.
66	*/
67	do_action( 'openstation_unfocus_effect_script_registered', $handle );
68
69	return true;
70	}
71
72	/**
73	* Internal module-level registry for unfocus-effect script handles.
74	*
75	* @internal
76	*
77	* @param string $handle Script handle to read or write.
78	* @param bool\|null $value Pass `true` to register; `null` to read only.
79	* @return array\|bool When called with no args returns the full store.
80	*/
81	function openstation_desktop_unfocus_effect_script_registry( $handle = '', $value = null ) {
82	static $store = array();
83
84	if ( '__flush__' === (string) $handle ) {
85	$store = array();
86	return array();
87	}
88	if ( '' === (string) $handle ) {
89	return $store;
90	}
91	if ( null !== $value ) {
92	$store[ (string) $handle ] = (bool) $value;
93	}
94	return isset( $store[ (string) $handle ] ) ? $store[ (string) $handle ] : false;
95	}
96
97	/**
98	* Test-only: clear the registry between PHPUnit cases. See
99	* {@see openstation_flush_script_handle_registries()}.
100	*/
101	function openstation_flush_desktop_unfocus_effect_script_registry() {
102	openstation_desktop_unfocus_effect_script_registry( '__flush__' );
103	}
104
105	/**
106	* Build the script-handle payload fed to the shell. Handles that
107	* aren't currently enqueued resolve to an empty URL and are dropped.
108	*
109	* @return array[] List of `{ handle, scriptUrl, … }` entries.
110	*/
111	function openstation_build_desktop_unfocus_effect_scripts_payload() {
112	$registry = openstation_desktop_unfocus_effect_script_registry();
113	if ( ! is_array( $registry ) \|\| empty( $registry ) ) {
114	return array();
115	}
116
117	$out = array();
118	$seen = array();
119	foreach ( $registry as $handle => $active ) {
120	if ( ! $active \|\| isset( $seen[ $handle ] ) ) {
121	continue;
122	}
123	$payload = openstation_resolve_script_payload( $handle );
124	if ( '' === $payload['url'] ) {
125	// Loud diagnostic — visible under WP_DEBUG. Deduped by
126	// `openstation_warn_unresolvable_script_handle` so the
127	// notice fires once per handle per request.
128	openstation_warn_unresolvable_script_handle(
129	'openstation_register_unfocus_effect_script',
130	'Unfocus effect',
131	(string) $handle
132	);
133	continue;
134	}
135	$out[] = array(
136	'handle' => (string) $handle,
137	'scriptUrl' => $payload['url'],
138	'scriptBefore' => $payload['before'],
139	'scriptAfter' => $payload['after'],
140	'scriptL10n' => $payload['l10n'],
141	'scriptTranslations' => $payload['translations'],
142	);
143	$seen[ $handle ] = true;
144	}
145	return $out;
146	}
147