← All changes | includes/settings-tabs.php +57 -51 0.9.8 → 1.1.10 View file →

		@@ -4,27 +4,27 @@
4	4	*
5	5	* Two entry points, mirroring the command-palette surface
6	6	* ({@see includes/commands.php}):
7	7	*
8		- * - `desktop_mode_register_settings_tab_script( $handle )` — primary,
	8	+ * - `openstation_register_settings_tab_script( $handle )` — primary,
9	9	* minimum-ceremony opt-in. Tells the shell: "this enqueued script
10	10	* registers OS Settings tabs; include it in the plugins-changed
11	11	* payload so it gets injected mid-session without a full reload."
12	12	*
13		- * - `desktop_mode_register_settings_tab( $args )` — optional. Declares
	13	+ * - `openstation_register_settings_tab( $args )` — optional. Declares
14	14	* tab metadata server-side so the shell can live-unregister tabs on
15	15	* plugin deactivation without the JS having to tag every
16	16	* `registerSettingsTab()` with an `owner`.
17	17	*
18		- * Both APIs feed `desktop_mode_build_desktop_settings_tab_scripts_payload()`
19		- * and `desktop_mode_build_desktop_settings_tabs_payload()`, which contribute
	18	+ * Both APIs feed `openstation_build_desktop_settings_tab_scripts_payload()`
	19	+ * and `openstation_build_desktop_settings_tabs_payload()`, which contribute
20	20	* `serverSettingsTabScripts` and `serverSettingsTabs` to the shell
21		- * payload in `desktop_mode_build_menu_payload()`.
	21	+ * payload in `openstation_build_menu_payload()`.
22	22	*
23	23	* The tab's `render` callback lives JS-side — the PHP layer only
24	24	* ferries identity and metadata.
25	25	*
26		- * @package WPDesktopMode
	26	+ * @package OpenStation
27	27	*/
28	28
29	29	defined( 'ABSPATH' ) || exit;
30	30
		@@ -37,30 +37,30 @@
37	37	* add_action( 'admin_enqueue_scripts', function () {
38	38	* wp_register_script(
39	39	* 'my-plugin-settings',
40	40	* plugins_url( 'js/settings.js', __FILE__ ),
41		- * array( 'desktop-mode' ),
	41	+ * array( 'openstation' ),
42	42	* '1.0.0',
43	43	* true
44	44	* );
45	45	* wp_enqueue_script( 'my-plugin-settings' );
46		- * } );
47		- * desktop_mode_register_settings_tab_script( 'my-plugin-settings' );
	46	+ * }, 5 ); // Before the shell harvests the payload at priority 10.
	47	+ * openstation_register_settings_tab_script( 'my-plugin-settings' );
48	48	* ```
49	49	*
50	50	* @param string $handle WP-registered script handle.
51	51	* @return true|WP_Error `true` on success; `WP_Error` on validation failure.
52	52	*/
53		-function desktop_mode_register_settings_tab_script( $handle ) {
	53	+function openstation_register_settings_tab_script( $handle ) {
54	54	$handle = (string) $handle;
55	55	if ( '' === $handle ) {
56		- return desktop_mode_registration_error(
57		- 'desktop_mode_missing_handle',
	56	+ return openstation_registration_error(
	57	+ 'openstation_missing_handle',
58	58	__( 'Settings tab script registration requires a non-empty script handle.', 'desktop-mode' )
59	59	);
60	60	}
61	61
62		- desktop_mode_desktop_settings_tab_script_registry( $handle, true );
	62	+ openstation_desktop_settings_tab_script_registry( $handle, true );
63	63
64	64	/**
65	65	* Fires after a desktop settings-tab script handle is registered.
66	66	*
		@@ -65,9 +65,9 @@
65	65	* Fires after a desktop settings-tab script handle is registered.
66	66	*
67	67	* @param string $handle The registered script handle.
68	68	*/
69		- do_action( 'desktop_mode_settings_tab_script_registered', $handle );
	69	+ do_action( 'openstation_settings_tab_script_registered', $handle );
70	70
71	71	return true;
72	72	}
73	73
		@@ -72,9 +72,9 @@
72	72	}
73	73
74	74	/**
75	75	* Declare an OS Settings tab server-side. Optional companion to
76		- * `desktop_mode_register_settings_tab_script()` — plugins that declare
	76	+ * `openstation_register_settings_tab_script()` — plugins that declare
77	77	* their tab here get live-unregister-on-deactivate for free; plugins
78	78	* that don't can still set `owner` on their JS `registerSettingsTab()`
79	79	* call, or accept "tab stays until next reload" as graceful fallback.
80	80	*
		@@ -80,9 +80,9 @@
80	80	*
81	81	* Example:
82	82	*
83	83	* ```php
84		- * desktop_mode_register_settings_tab( array(
	84	+ * openstation_register_settings_tab( array(
85	85	* 'id' => 'my-plugin',
86	86	* 'label' => __( 'My Plugin', 'my-plugin' ),
87	87	* 'capability' => 'manage_options',
88	88	* 'order' => 50,
		@@ -90,9 +90,9 @@
90	90	* ) );
91	91	* ```
92	92	*
93	93	* Implicitly registers the `script` handle via
94		- * `desktop_mode_register_settings_tab_script()` when provided.
	94	+ * `openstation_register_settings_tab_script()` when provided.
95	95	*
96	96	* @param array $args {
97	97	* @type string $id Unique tab id, `[a-z0-9_-]+`. Required.
98	98	* @type string $label Human-readable tab label. Required.
		@@ -109,9 +109,9 @@
109	109	* Default empty.
110	110	* }
111	111	* @return true|WP_Error `true` on success; `WP_Error` on validation failure.
112	112	*/
113		-function desktop_mode_register_settings_tab( $args = array() ) {
	113	+function openstation_register_settings_tab( $args = array() ) {
114	114	$defaults = array(
115	115	'id' => '',
116	116	'label' => '',
117	117	'capability' => '',
		@@ -121,17 +121,17 @@
121	121	$args = wp_parse_args( $args, $defaults );
122	122
123	123	$id = (string) $args['id'];
124	124	if ( '' === $id || ! preg_match( '/^[a-z0-9_\-]+$/', $id ) ) {
125		- return desktop_mode_registration_error(
126		- 'desktop_mode_invalid_id',
	125	+ return openstation_registration_error(
	126	+ 'openstation_invalid_id',
127	127	__( 'Settings tab registration requires a non-empty `id` matching [a-z0-9_-]+.', 'desktop-mode' ),
128	128	array( 'id' => $id )
129	129	);
130	130	}
131	131	if ( '' === (string) $args['label'] ) {
132		- return desktop_mode_registration_error(
133		- 'desktop_mode_missing_label',
	132	+ return openstation_registration_error(
	133	+ 'openstation_missing_label',
134	134	__( 'Settings tab registration requires a non-empty `label`.', 'desktop-mode' ),
135	135	array( 'id' => $id )
136	136	);
137	137	}
		@@ -142,12 +142,12 @@
142	142	'capability' => (string) $args['capability'],
143	143	'order' => (int) $args['order'],
144	144	'script' => (string) $args['script'],
145	145	);
146		- desktop_mode_desktop_settings_tab_registry( $id, $entry );
	146	+ openstation_desktop_settings_tab_registry( $id, $entry );
147	147
148	148	if ( '' !== $entry['script'] ) {
149		- desktop_mode_register_settings_tab_script( $entry['script'] );
	149	+ openstation_register_settings_tab_script( $entry['script'] );
150	150	}
151	151
152	152	/**
153	153	* Fires after a desktop settings tab is successfully registered.
		@@ -154,9 +154,9 @@
154	154	*
155	155	* @param string $id The tab id.
156	156	* @param array $entry The stored registry entry.
157	157	*/
158		- do_action( 'desktop_mode_settings_tab_registered', $id, $entry );
	158	+ do_action( 'openstation_settings_tab_registered', $id, $entry );
159	159
160	160	return true;
161	161	}
162	162
		@@ -161,9 +161,9 @@
161	161	}
162	162
163	163	/**
164	164	* Internal module-level registry for settings-tab script handles
165		- * declared via {@see desktop_mode_register_settings_tab_script()}.
	165	+ * declared via {@see openstation_register_settings_tab_script()}.
166	166	*
167	167	* @internal
168	168	*
169	169	* @param string $handle Script handle to read or write.
		@@ -169,9 +169,9 @@
169	169	* @param string $handle Script handle to read or write.
170	170	* @param bool|null $value Pass `true` to register; `null` to read only.
171	171	* @return array|bool When called with no args returns the full store.
172	172	*/
173		-function desktop_mode_desktop_settings_tab_script_registry( $handle = '', $value = null ) {
	173	+function openstation_desktop_settings_tab_script_registry( $handle = '', $value = null ) {
174	174	static $store = array();
175	175
176	176	if ( '__flush__' === (string) $handle ) {
177	177	$store = array();
		@@ -187,17 +187,17 @@
187	187	}
188	188
189	189	/**
190	190	* Test-only: clear the registry between PHPUnit cases. See
191		- * {@see desktop_mode_flush_script_handle_registries()}.
	191	+ * {@see openstation_flush_script_handle_registries()}.
192	192	*/
193		-function desktop_mode_flush_desktop_settings_tab_script_registry() {
194		- desktop_mode_desktop_settings_tab_script_registry( '__flush__' );
	193	+function openstation_flush_desktop_settings_tab_script_registry() {
	194	+ openstation_desktop_settings_tab_script_registry( '__flush__' );
195	195	}
196	196
197	197	/**
198	198	* Internal module-level registry for tabs declared via
199		- * {@see desktop_mode_register_settings_tab()}.
	199	+ * {@see openstation_register_settings_tab()}.
200	200	*
201	201	* @internal
202	202	*
203	203	* @param string $id Tab id to read or write.
		@@ -203,9 +203,9 @@
203	203	* @param string $id Tab id to read or write.
204	204	* @param array|null $entry Entry to store, or `null` to read.
205	205	* @return array|null
206	206	*/
207		-function desktop_mode_desktop_settings_tab_registry( $id = '', $entry = null ) {
	207	+function openstation_desktop_settings_tab_registry( $id = '', $entry = null ) {
208	208	static $store = array();
209	209
210	210	if ( '' === (string) $id ) {
211	211	return $store;
		@@ -222,10 +222,10 @@
222	222	* matches the command-scripts payload builder.
223	223	*
224	224	* @return array[] List of `{ handle, scriptUrl, scriptBefore, scriptAfter, scriptL10n, scriptTranslations }` entries.
225	225	*/
226		-function desktop_mode_build_desktop_settings_tab_scripts_payload() {
227		- $registry = desktop_mode_desktop_settings_tab_script_registry();
	226	+function openstation_build_desktop_settings_tab_scripts_payload() {
	227	+ $registry = openstation_desktop_settings_tab_script_registry();
228	228	if ( ! is_array( $registry ) || empty( $registry ) ) {
229	229	return array();
230	230	}
231	231
		@@ -234,12 +234,12 @@
234	234	foreach ( $registry as $handle => $active ) {
235	235	if ( ! $active || isset( $seen[ $handle ] ) ) {
236	236	continue;
237	237	}
238		- $payload = desktop_mode_resolve_script_payload( $handle );
	238	+ $payload = openstation_resolve_script_payload( $handle );
239	239	if ( '' === $payload['url'] ) {
240		- desktop_mode_warn_unresolvable_script_handle(
241		- 'desktop_mode_register_settings_tab_script',
	240	+ openstation_warn_unresolvable_script_handle(
	241	+ 'openstation_register_settings_tab_script',
242	242	'Settings-tab',
243	243	(string) $handle
244	244	);
245	245	continue;
		@@ -250,8 +250,11 @@
250	250	'scriptBefore' => $payload['before'],
251	251	'scriptAfter' => $payload['after'],
252	252	'scriptL10n' => $payload['l10n'],
253	253	'scriptTranslations' => $payload['translations'],
	254	+ // The handle's dependency closure, replayed before the bundle
	255	+ // on its lazy load — see `openstation_resolve_script_dependencies()`.
	256	+ 'scriptDeps' => openstation_resolve_script_dependencies( $handle ),
254	257	);
255	258	$seen[ $handle ] = true;
256	259	}
257	260	return $out;
		@@ -258,9 +261,9 @@
258	261	}
259	262
260	263	/**
261	264	* Build the metadata payload for tabs declared via
262		- * {@see desktop_mode_register_settings_tab()}. Each entry carries the
	265	+ * {@see openstation_register_settings_tab()}. Each entry carries the
263	266	* resolved `scriptUrl` alongside metadata so the shell's sync can
264	267	* unregister tabs attributable to a script handle that just left the
265	268	* `serverSettingsTabScripts` payload.
266	269	*
		@@ -265,10 +268,10 @@
265	268	* `serverSettingsTabScripts` payload.
266	269	*
267	270	* @return array[]
268	271	*/
269		-function desktop_mode_build_desktop_settings_tabs_payload() {
270		- $registry = desktop_mode_desktop_settings_tab_registry();
	272	+function openstation_build_desktop_settings_tabs_payload() {
	273	+ $registry = openstation_desktop_settings_tab_registry();
271	274	if ( ! is_array( $registry ) || empty( $registry ) ) {
272	275	return array();
273	276	}
274	277
		@@ -275,9 +278,9 @@
275	278	$out = array();
276	279	foreach ( $registry as $entry ) {
277	280	$handle = (string) $entry['script'];
278	281	$payload = '' !== $handle
279		- ? desktop_mode_resolve_script_payload( $handle )
	282	+ ? openstation_resolve_script_payload( $handle )
280	283	: array(
281	284	'url' => '',
282	285	'before' => array(),
283	286	'after' => array(),
		@@ -283,19 +286,22 @@
283	286	'after' => array(),
284	287	'l10n' => array(),
285	288	'translations' => '',
286	289	);
287		- $out[] = array(
288		- 'id' => (string) $entry['id'],
289		- 'label' => (string) $entry['label'],
290		- 'capability' => (string) $entry['capability'],
291		- 'order' => (int) $entry['order'],
292		- 'scriptUrl' => $payload['url'],
293		- 'scriptHandle' => $handle,
294		- 'scriptBefore' => $payload['before'],
295		- 'scriptAfter' => $payload['after'],
296		- 'scriptL10n' => $payload['l10n'],
	290	+ $out[] = array(
	291	+ 'id' => (string) $entry['id'],
	292	+ 'label' => (string) $entry['label'],
	293	+ 'capability' => (string) $entry['capability'],
	294	+ 'order' => (int) $entry['order'],
	295	+ 'scriptUrl' => $payload['url'],
	296	+ 'scriptHandle' => $handle,
	297	+ 'scriptBefore' => $payload['before'],
	298	+ 'scriptAfter' => $payload['after'],
	299	+ 'scriptL10n' => $payload['l10n'],
297	300	'scriptTranslations' => $payload['translations'],
	301	+ // The handle's dependency closure, replayed before the bundle
	302	+ // on its lazy load — see `openstation_resolve_script_dependencies()`.
	303	+ 'scriptDeps' => openstation_resolve_script_dependencies( $handle ),
298	304	);
299	305	}
300	306	return $out;
301	307	}