← All changes | includes/unfocus-effects.php +24 -31 0.9.2 → 1.1.10 View file →

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