← All changes | includes/commands.php +63 -57 0.9.8 → 1.1.10 View file →

		@@ -4,25 +4,25 @@
4	4	*
5	5	* Two entry points, mirroring the rest of the plugin surface but tuned
6	6	* for the command-palette use case:
7	7	*
8		- * - `desktop_mode_register_command_script( $handle )` — primary, minimum-
	8	+ * - `openstation_register_command_script( $handle )` — primary, minimum-
9	9	* ceremony opt-in. Tells the shell: "this enqueued script registers
10	10	* slash-commands; include it in the plugins-changed payload so it
11	11	* gets injected into the shell page mid-session when my plugin is
12	12	* installed or activated without a full reload."
13	13	*
14		- * - `desktop_mode_register_command( $args )` — optional. Plugins that
	14	+ * - `openstation_register_command( $args )` — optional. Plugins that
15	15	* want to declare command metadata server-side (for discoverability
16	16	* tooling, REST enumeration, future pre-registration shims) use this.
17	17	* The `run` function still lives JS-side; metadata is advisory today.
18	18	*
19		- * Both APIs feed `desktop_mode_build_desktop_command_scripts_payload()` and
20		- * `desktop_mode_build_desktop_commands_payload()`, which contribute
	19	+ * Both APIs feed `openstation_build_desktop_command_scripts_payload()` and
	20	+ * `openstation_build_desktop_commands_payload()`, which contribute
21	21	* `serverCommandScripts` and `serverCommands` to the shell payload in
22		- * `desktop_mode_build_menu_payload()`.
	22	+ * `openstation_build_menu_payload()`.
23	23	*
24		- * @package WPDesktopMode
	24	+ * @package OpenStation
25	25	*/
26	26
27	27	defined( 'ABSPATH' ) || exit;
28	28
		@@ -35,20 +35,20 @@
35	35	* add_action( 'admin_enqueue_scripts', function () {
36	36	* wp_register_script(
37	37	* 'home-assistant-commands',
38	38	* plugins_url( 'js/commands.js', __FILE__ ),
39		- * array( 'desktop-mode' ),
	39	+ * array( 'openstation' ),
40	40	* '1.0.0',
41	41	* true
42	42	* );
43	43	* wp_enqueue_script( 'home-assistant-commands' );
44		- * } );
45		- * desktop_mode_register_command_script( 'home-assistant-commands' );
	44	+ * }, 5 ); // Before the shell harvests the payload at priority 10.
	45	+ * openstation_register_command_script( 'home-assistant-commands' );
46	46	* ```
47	47	*
48		- * The script's JS side calls `wp.desktop.registerCommand( { … } )` as
	48	+ * The script's JS side calls `wp.os.registerCommand( { … } )` as
49	49	* usual. When a user installs or activates the plugin, the chromeless
50		- * bridge's `desktop-mode-plugins-changed` payload includes the resolved
	50	+ * bridge's `os-plugins-changed` payload includes the resolved
51	51	* script URL; the shell's command-sync module injects the script into
52	52	* the shell page and the new commands appear in the palette without a
53	53	* full reload.
54	54	*
		@@ -54,18 +54,18 @@
54	54	*
55	55	* @param string $handle WP-registered script handle.
56	56	* @return true|WP_Error `true` on success; `WP_Error` on validation failure.
57	57	*/
58		-function desktop_mode_register_command_script( $handle ) {
	58	+function openstation_register_command_script( $handle ) {
59	59	$handle = (string) $handle;
60	60	if ( '' === $handle ) {
61		- return desktop_mode_registration_error(
62		- 'desktop_mode_missing_handle',
	61	+ return openstation_registration_error(
	62	+ 'openstation_missing_handle',
63	63	__( 'Command script registration requires a non-empty script handle.', 'desktop-mode' )
64	64	);
65	65	}
66	66
67		- desktop_mode_desktop_command_script_registry( $handle, true );
	67	+ openstation_desktop_command_script_registry( $handle, true );
68	68
69	69	/**
70	70	* Fires after a desktop command script handle is registered.
71	71	*
		@@ -70,9 +70,9 @@
70	70	* Fires after a desktop command script handle is registered.
71	71	*
72	72	* @param string $handle The registered script handle.
73	73	*/
74		- do_action( 'desktop_mode_command_script_registered', $handle );
	74	+ do_action( 'openstation_command_script_registered', $handle );
75	75
76	76	return true;
77	77	}
78	78
		@@ -77,9 +77,9 @@
77	77	}
78	78
79	79	/**
80	80	* Declare a desktop command server-side. Optional companion to
81		- * `desktop_mode_register_command_script()` for plugins that want metadata
	81	+ * `openstation_register_command_script()` for plugins that want metadata
82	82	* enumerable without JS execution (REST, future pre-registration, etc.).
83	83	* The command's `run` function still lives JS-side; this function only
84	84	* stores metadata.
85	85	*
		@@ -85,9 +85,9 @@
85	85	*
86	86	* Example:
87	87	*
88	88	* ```php
89		- * desktop_mode_register_command( array(
	89	+ * openstation_register_command( array(
90	90	* 'slug' => 'ha-lights',
91	91	* 'label' => __( 'Home Assistant: Lights', 'home-assistant' ),
92	92	* 'description' => __( 'Toggle smart lights from the palette.', 'home-assistant' ),
93	93	* 'icon' => 'dashicons-lightbulb',
		@@ -96,9 +96,9 @@
96	96	* ) );
97	97	* ```
98	98	*
99	99	* Implicitly registers the `script` handle via
100		- * `desktop_mode_register_command_script()` when provided, so plugins using
	100	+ * `openstation_register_command_script()` when provided, so plugins using
101	101	* this API don't need to call both functions.
102	102	*
103	103	* @param array $args {
104	104	* @type string $slug Slash-command slug (without leading `/`). Required.
		@@ -106,14 +106,14 @@
106	106	* @type string $description Subtitle shown in the palette. Default empty.
107	107	* @type string $icon Dashicons class. Default `dashicons-arrow-right-alt`.
108	108	* @type string $hint Argument hint rendered next to the slug. Default empty.
109	109	* @type string $script WP script handle providing the `run` function.
110		- * Registered via `desktop_mode_register_command_script()`
	110	+ * Registered via `openstation_register_command_script()`
111	111	* when present. Default empty (advisory registration only).
112	112	* }
113	113	* @return true|WP_Error `true` on success; `WP_Error` on validation failure.
114	114	*/
115		-function desktop_mode_register_command( $args = array() ) {
	115	+function openstation_register_command( $args = array() ) {
116	116	$defaults = array(
117	117	'slug' => '',
118	118	'label' => '',
119	119	'description' => '',
		@@ -120,20 +120,20 @@
120	120	'icon' => 'dashicons-arrow-right-alt',
121	121	'hint' => '',
122	122	'script' => '',
123	123	);
124		- $args = wp_parse_args( $args, $defaults );
	124	+ $args = wp_parse_args( $args, $defaults );
125	125
126	126	$slug = (string) $args['slug'];
127	127	if ( '' === $slug ) {
128		- return desktop_mode_registration_error(
129		- 'desktop_mode_missing_slug',
	128	+ return openstation_registration_error(
	129	+ 'openstation_missing_slug',
130	130	__( 'Command registration requires a non-empty `slug`.', 'desktop-mode' )
131	131	);
132	132	}
133	133	if ( '' === (string) $args['label'] ) {
134		- return desktop_mode_registration_error(
135		- 'desktop_mode_missing_label',
	134	+ return openstation_registration_error(
	135	+ 'openstation_missing_label',
136	136	__( 'Command registration requires a non-empty `label`.', 'desktop-mode' ),
137	137	array( 'slug' => $slug )
138	138	);
139	139	}
		@@ -145,12 +145,12 @@
145	145	'icon' => (string) $args['icon'],
146	146	'hint' => (string) $args['hint'],
147	147	'script' => (string) $args['script'],
148	148	);
149		- desktop_mode_desktop_command_registry( $slug, $entry );
	149	+ openstation_desktop_command_registry( $slug, $entry );
150	150
151	151	if ( '' !== $entry['script'] ) {
152		- desktop_mode_register_command_script( $entry['script'] );
	152	+ openstation_register_command_script( $entry['script'] );
153	153	}
154	154
155	155	/**
156	156	* Fires after a desktop command is successfully registered.
		@@ -157,9 +157,9 @@
157	157	*
158	158	* @param string $slug The command slug.
159	159	* @param array $entry The stored registry entry.
160	160	*/
161		- do_action( 'desktop_mode_command_registered', $slug, $entry );
	161	+ do_action( 'openstation_command_registered', $slug, $entry );
162	162
163	163	return true;
164	164	}
165	165
		@@ -164,9 +164,9 @@
164	164	}
165	165
166	166	/**
167	167	* Internal module-level registry for command script handles declared
168		- * via {@see desktop_mode_register_command_script()}. Accessed by both the
	168	+ * via {@see openstation_register_command_script()}. Accessed by both the
169	169	* registration API (write) and the payload builder (read).
170	170	*
171	171	* @internal
172	172	*
		@@ -173,9 +173,9 @@
173	173	* @param string $handle Script handle to read or write.
174	174	* @param bool|null $value Pass `true` to register; `null` to read only.
175	175	* @return array|bool When called with no args returns the full store.
176	176	*/
177		-function desktop_mode_desktop_command_script_registry( $handle = '', $value = null ) {
	177	+function openstation_desktop_command_script_registry( $handle = '', $value = null ) {
178	178	static $store = array();
179	179
180	180	if ( '__flush__' === (string) $handle ) {
181	181	$store = array();
		@@ -194,15 +194,15 @@
194	194	* Flush the command-script registry. Tests call this in `set_up` so
195	195	* a previous test's stale handle doesn't leak into the next test's
196	196	* payload-build assertions. No production caller.
197	197	*/
198		-function desktop_mode_flush_desktop_command_script_registry() {
199		- desktop_mode_desktop_command_script_registry( '__flush__' );
	198	+function openstation_flush_desktop_command_script_registry() {
	199	+ openstation_desktop_command_script_registry( '__flush__' );
200	200	}
201	201
202	202	/**
203	203	* Internal module-level registry for commands declared via
204		- * {@see desktop_mode_register_command()}.
	204	+ * {@see openstation_register_command()}.
205	205	*
206	206	* @internal
207	207	*
208	208	* @param string $slug Slug to read or write.
		@@ -208,9 +208,9 @@
208	208	* @param string $slug Slug to read or write.
209	209	* @param array|null $entry Entry to store, or `null` to read.
210	210	* @return array|null
211	211	*/
212		-function desktop_mode_desktop_command_registry( $slug = '', $entry = null ) {
	212	+function openstation_desktop_command_registry( $slug = '', $entry = null ) {
213	213	static $store = array();
214	214
215	215	if ( '' === (string) $slug ) {
216	216	return $store;
		@@ -222,9 +222,9 @@
222	222	}
223	223
224	224	/**
225	225	* Build the script-handle payload fed to the shell. Resolves each
226		- * registered handle to a full payload via {@see desktop_mode_resolve_script_payload()};
	226	+ * registered handle to a full payload via {@see openstation_resolve_script_payload()};
227	227	* handles that aren't currently enqueued (plugin not active this request)
228	228	* resolve to an empty URL and are dropped. The harvested `extra` data
229	229	* (localize / inline / translations) ships alongside the URL so the
230	230	* shell's lazy `<script>` injection doesn't drop it the way a bare
		@@ -231,10 +231,10 @@
231	231	* `<script src="…">` append would.
232	232	*
233	233	* @return array[] List of `{ handle, scriptUrl, scriptBefore, scriptAfter, scriptL10n, scriptTranslations }` entries.
234	234	*/
235		-function desktop_mode_build_desktop_command_scripts_payload() {
236		- $registry = desktop_mode_desktop_command_script_registry();
	235	+function openstation_build_desktop_command_scripts_payload() {
	236	+ $registry = openstation_desktop_command_script_registry();
237	237	if ( ! is_array( $registry ) || empty( $registry ) ) {
238	238	return array();
239	239	}
240	240
		@@ -243,18 +243,18 @@
243	243	foreach ( $registry as $handle => $active ) {
244	244	if ( ! $active || isset( $seen[ $handle ] ) ) {
245	245	continue;
246	246	}
247		- $payload = desktop_mode_resolve_script_payload( $handle );
	247	+ $payload = openstation_resolve_script_payload( $handle );
248	248	if ( '' === $payload['url'] ) {
249		- desktop_mode_warn_unresolvable_script_handle(
250		- 'desktop_mode_register_command_script',
	249	+ openstation_warn_unresolvable_script_handle(
	250	+ 'openstation_register_command_script',
251	251	'Command',
252	252	(string) $handle
253	253	);
254	254	continue;
255	255	}
256		- $out[] = array(
	256	+ $out[] = array(
257	257	'handle' => (string) $handle,
258	258	'scriptUrl' => $payload['url'],
259	259	'scriptBefore' => $payload['before'],
260	260	'scriptAfter' => $payload['after'],
		@@ -259,8 +259,11 @@
259	259	'scriptBefore' => $payload['before'],
260	260	'scriptAfter' => $payload['after'],
261	261	'scriptL10n' => $payload['l10n'],
262	262	'scriptTranslations' => $payload['translations'],
	263	+ // The handle's dependency closure, replayed before the bundle
	264	+ // on its lazy load — see `openstation_resolve_script_dependencies()`.
	265	+ 'scriptDeps' => openstation_resolve_script_dependencies( $handle ),
263	266	);
264	267	$seen[ $handle ] = true;
265	268	}
266	269	return $out;
		@@ -267,9 +270,9 @@
267	270	}
268	271
269	272	/**
270	273	* Build the metadata payload for commands declared via
271		- * {@see desktop_mode_register_command()}. Each entry carries the resolved
	274	+ * {@see openstation_register_command()}. Each entry carries the resolved
272	275	* `scriptUrl` alongside metadata so the shell's sync knows which script
273	276	* contributed it — enables future pre-registration shims without a round
274	277	* trip.
275	278	*
		@@ -274,10 +277,10 @@
274	277	* trip.
275	278	*
276	279	* @return array[]
277	280	*/
278		-function desktop_mode_build_desktop_commands_payload() {
279		- $registry = desktop_mode_desktop_command_registry();
	281	+function openstation_build_desktop_commands_payload() {
	282	+ $registry = openstation_desktop_command_registry();
280	283	if ( ! is_array( $registry ) || empty( $registry ) ) {
281	284	return array();
282	285	}
283	286
		@@ -284,9 +287,9 @@
284	287	$out = array();
285	288	foreach ( $registry as $entry ) {
286	289	$handle = (string) $entry['script'];
287	290	$payload = '' !== $handle
288		- ? desktop_mode_resolve_script_payload( $handle )
	291	+ ? openstation_resolve_script_payload( $handle )
289	292	: array(
290	293	'url' => '',
291	294	'before' => array(),
292	295	'after' => array(),
		@@ -292,20 +295,23 @@
292	295	'after' => array(),
293	296	'l10n' => array(),
294	297	'translations' => '',
295	298	);
296		- $out[] = array(
297		- 'slug' => (string) $entry['slug'],
298		- 'label' => (string) $entry['label'],
299		- 'description' => (string) $entry['description'],
300		- 'icon' => (string) $entry['icon'],
301		- 'hint' => (string) $entry['hint'],
302		- 'scriptUrl' => $payload['url'],
303		- 'scriptHandle' => $handle,
304		- 'scriptBefore' => $payload['before'],
305		- 'scriptAfter' => $payload['after'],
306		- 'scriptL10n' => $payload['l10n'],
	299	+ $out[] = array(
	300	+ 'slug' => (string) $entry['slug'],
	301	+ 'label' => (string) $entry['label'],
	302	+ 'description' => (string) $entry['description'],
	303	+ 'icon' => (string) $entry['icon'],
	304	+ 'hint' => (string) $entry['hint'],
	305	+ 'scriptUrl' => $payload['url'],
	306	+ 'scriptHandle' => $handle,
	307	+ 'scriptBefore' => $payload['before'],
	308	+ 'scriptAfter' => $payload['after'],
	309	+ 'scriptL10n' => $payload['l10n'],
307	310	'scriptTranslations' => $payload['translations'],
	311	+ // The handle's dependency closure, replayed before the bundle
	312	+ // on its lazy load — see `openstation_resolve_script_dependencies()`.
	313	+ 'scriptDeps' => openstation_resolve_script_dependencies( $handle ),
308	314	);
309	315	}
310	316	return $out;
311	317	}