← All changes | includes/settings-tabs.php +58 -69 0.9.5 → 1.1.10 View file →

		@@ -4,28 +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		- * @since 0.5.1
27		- * @package WPDesktopMode
	26	+ * @package OpenStation
28	27	*/
29	28
30	29	defined( 'ABSPATH' ) || exit;
31	30
		@@ -38,41 +37,37 @@
38	37	* add_action( 'admin_enqueue_scripts', function () {
39	38	* wp_register_script(
40	39	* 'my-plugin-settings',
41	40	* plugins_url( 'js/settings.js', __FILE__ ),
42		- * array( 'desktop-mode' ),
	41	+ * array( 'openstation' ),
43	42	* '1.0.0',
44	43	* true
45	44	* );
46	45	* wp_enqueue_script( 'my-plugin-settings' );
47		- * } );
48		- * 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' );
49	48	* ```
50	49	*
51		- * @since 0.5.1
52		- *
53	50	* @param string $handle WP-registered script handle.
54	51	* @return true|WP_Error `true` on success; `WP_Error` on validation failure.
55	52	*/
56		-function desktop_mode_register_settings_tab_script( $handle ) {
	53	+function openstation_register_settings_tab_script( $handle ) {
57	54	$handle = (string) $handle;
58	55	if ( '' === $handle ) {
59		- return desktop_mode_registration_error(
60		- 'desktop_mode_missing_handle',
	56	+ return openstation_registration_error(
	57	+ 'openstation_missing_handle',
61	58	__( 'Settings tab script registration requires a non-empty script handle.', 'desktop-mode' )
62	59	);
63	60	}
64	61
65		- desktop_mode_desktop_settings_tab_script_registry( $handle, true );
	62	+ openstation_desktop_settings_tab_script_registry( $handle, true );
66	63
67	64	/**
68	65	* Fires after a desktop settings-tab script handle is registered.
69	66	*
70		- * @since 0.5.1
71		- *
72	67	* @param string $handle The registered script handle.
73	68	*/
74		- do_action( 'desktop_mode_settings_tab_script_registered', $handle );
	69	+ do_action( 'openstation_settings_tab_script_registered', $handle );
75	70
76	71	return true;
77	72	}
78	73
		@@ -77,9 +72,9 @@
77	72	}
78	73
79	74	/**
80	75	* Declare an OS Settings tab server-side. Optional companion to
81		- * `desktop_mode_register_settings_tab_script()` — plugins that declare
	76	+ * `openstation_register_settings_tab_script()` — plugins that declare
82	77	* their tab here get live-unregister-on-deactivate for free; plugins
83	78	* that don't can still set `owner` on their JS `registerSettingsTab()`
84	79	* call, or accept "tab stays until next reload" as graceful fallback.
85	80	*
		@@ -85,9 +80,9 @@
85	80	*
86	81	* Example:
87	82	*
88	83	* ```php
89		- * desktop_mode_register_settings_tab( array(
	84	+ * openstation_register_settings_tab( array(
90	85	* 'id' => 'my-plugin',
91	86	* 'label' => __( 'My Plugin', 'my-plugin' ),
92	87	* 'capability' => 'manage_options',
93	88	* 'order' => 50,
		@@ -95,12 +90,10 @@
95	90	* ) );
96	91	* ```
97	92	*
98	93	* Implicitly registers the `script` handle via
99		- * `desktop_mode_register_settings_tab_script()` when provided.
	94	+ * `openstation_register_settings_tab_script()` when provided.
100	95	*
101		- * @since 0.5.1
102		- *
103	96	* @param array $args {
104	97	* @type string $id Unique tab id, `[a-z0-9_-]+`. Required.
105	98	* @type string $label Human-readable tab label. Required.
106	99	* @type string $capability Required capability to see the tab.
		@@ -107,9 +100,9 @@
107	100	* Shell today maps this to `isAdmin` gating
108	101	* (`manage_options` → admin-only; anything
109	102	* else → visible to everyone). Default empty.
110	103	* @type int $order Sort order relative to built-in tabs
111		- * (appearance=10, ai=20, features=25,
	104	+ * (appearance=10, themes=12, features=25,
112	105	* help=40). Default 100 (appended).
113	106	* @type string $script WP script handle providing the
114	107	* `registerSettingsTab()` call.
115	108	* Registered implicitly when present.
		@@ -116,9 +109,9 @@
116	109	* Default empty.
117	110	* }
118	111	* @return true|WP_Error `true` on success; `WP_Error` on validation failure.
119	112	*/
120		-function desktop_mode_register_settings_tab( $args = array() ) {
	113	+function openstation_register_settings_tab( $args = array() ) {
121	114	$defaults = array(
122	115	'id' => '',
123	116	'label' => '',
124	117	'capability' => '',
		@@ -128,17 +121,17 @@
128	121	$args = wp_parse_args( $args, $defaults );
129	122
130	123	$id = (string) $args['id'];
131	124	if ( '' === $id || ! preg_match( '/^[a-z0-9_\-]+$/', $id ) ) {
132		- return desktop_mode_registration_error(
133		- 'desktop_mode_invalid_id',
	125	+ return openstation_registration_error(
	126	+ 'openstation_invalid_id',
134	127	__( 'Settings tab registration requires a non-empty `id` matching [a-z0-9_-]+.', 'desktop-mode' ),
135	128	array( 'id' => $id )
136	129	);
137	130	}
138	131	if ( '' === (string) $args['label'] ) {
139		- return desktop_mode_registration_error(
140		- 'desktop_mode_missing_label',
	132	+ return openstation_registration_error(
	133	+ 'openstation_missing_label',
141	134	__( 'Settings tab registration requires a non-empty `label`.', 'desktop-mode' ),
142	135	array( 'id' => $id )
143	136	);
144	137	}
		@@ -149,23 +142,21 @@
149	142	'capability' => (string) $args['capability'],
150	143	'order' => (int) $args['order'],
151	144	'script' => (string) $args['script'],
152	145	);
153		- desktop_mode_desktop_settings_tab_registry( $id, $entry );
	146	+ openstation_desktop_settings_tab_registry( $id, $entry );
154	147
155	148	if ( '' !== $entry['script'] ) {
156		- desktop_mode_register_settings_tab_script( $entry['script'] );
	149	+ openstation_register_settings_tab_script( $entry['script'] );
157	150	}
158	151
159	152	/**
160	153	* Fires after a desktop settings tab is successfully registered.
161	154	*
162		- * @since 0.5.1
163		- *
164	155	* @param string $id The tab id.
165	156	* @param array $entry The stored registry entry.
166	157	*/
167		- do_action( 'desktop_mode_settings_tab_registered', $id, $entry );
	158	+ do_action( 'openstation_settings_tab_registered', $id, $entry );
168	159
169	160	return true;
170	161	}
171	162
		@@ -170,11 +161,10 @@
170	161	}
171	162
172	163	/**
173	164	* Internal module-level registry for settings-tab script handles
174		- * declared via {@see desktop_mode_register_settings_tab_script()}.
	165	+ * declared via {@see openstation_register_settings_tab_script()}.
175	166	*
176		- * @since 0.5.1
177	167	* @internal
178	168	*
179	169	* @param string $handle Script handle to read or write.
180	170	* @param bool|null $value Pass `true` to register; `null` to read only.
		@@ -179,9 +169,9 @@
179	169	* @param string $handle Script handle to read or write.
180	170	* @param bool|null $value Pass `true` to register; `null` to read only.
181	171	* @return array|bool When called with no args returns the full store.
182	172	*/
183		-function desktop_mode_desktop_settings_tab_script_registry( $handle = '', $value = null ) {
	173	+function openstation_desktop_settings_tab_script_registry( $handle = '', $value = null ) {
184	174	static $store = array();
185	175
186	176	if ( '__flush__' === (string) $handle ) {
187	177	$store = array();
		@@ -197,21 +187,18 @@
197	187	}
198	188
199	189	/**
200	190	* Test-only: clear the registry between PHPUnit cases. See
201		- * {@see desktop_mode_flush_script_handle_registries()}.
202		- *
203		- * @since 0.5.2
	191	+ * {@see openstation_flush_script_handle_registries()}.
204	192	*/
205		-function desktop_mode_flush_desktop_settings_tab_script_registry() {
206		- 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__' );
207	195	}
208	196
209	197	/**
210	198	* Internal module-level registry for tabs declared via
211		- * {@see desktop_mode_register_settings_tab()}.
	199	+ * {@see openstation_register_settings_tab()}.
212	200	*
213		- * @since 0.5.1
214	201	* @internal
215	202	*
216	203	* @param string $id Tab id to read or write.
217	204	* @param array|null $entry Entry to store, or `null` to read.
		@@ -216,9 +203,9 @@
216	203	* @param string $id Tab id to read or write.
217	204	* @param array|null $entry Entry to store, or `null` to read.
218	205	* @return array|null
219	206	*/
220		-function desktop_mode_desktop_settings_tab_registry( $id = '', $entry = null ) {
	207	+function openstation_desktop_settings_tab_registry( $id = '', $entry = null ) {
221	208	static $store = array();
222	209
223	210	if ( '' === (string) $id ) {
224	211	return $store;
		@@ -233,14 +220,12 @@
233	220	* Build the script-handle payload fed to the shell. Handles that
234	221	* aren't currently enqueued resolve to an empty URL and are dropped —
235	222	* matches the command-scripts payload builder.
236	223	*
237		- * @since 0.5.1
238		- *
239	224	* @return array[] List of `{ handle, scriptUrl, scriptBefore, scriptAfter, scriptL10n, scriptTranslations }` entries.
240	225	*/
241		-function desktop_mode_build_desktop_settings_tab_scripts_payload() {
242		- $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();
243	228	if ( ! is_array( $registry ) || empty( $registry ) ) {
244	229	return array();
245	230	}
246	231
		@@ -249,12 +234,12 @@
249	234	foreach ( $registry as $handle => $active ) {
250	235	if ( ! $active || isset( $seen[ $handle ] ) ) {
251	236	continue;
252	237	}
253		- $payload = desktop_mode_resolve_script_payload( $handle );
	238	+ $payload = openstation_resolve_script_payload( $handle );
254	239	if ( '' === $payload['url'] ) {
255		- desktop_mode_warn_unresolvable_script_handle(
256		- 'desktop_mode_register_settings_tab_script',
	240	+ openstation_warn_unresolvable_script_handle(
	241	+ 'openstation_register_settings_tab_script',
257	242	'Settings-tab',
258	243	(string) $handle
259	244	);
260	245	continue;
		@@ -265,8 +250,11 @@
265	250	'scriptBefore' => $payload['before'],
266	251	'scriptAfter' => $payload['after'],
267	252	'scriptL10n' => $payload['l10n'],
268	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 ),
269	257	);
270	258	$seen[ $handle ] = true;
271	259	}
272	260	return $out;
		@@ -273,19 +261,17 @@
273	261	}
274	262
275	263	/**
276	264	* Build the metadata payload for tabs declared via
277		- * {@see desktop_mode_register_settings_tab()}. Each entry carries the
	265	+ * {@see openstation_register_settings_tab()}. Each entry carries the
278	266	* resolved `scriptUrl` alongside metadata so the shell's sync can
279	267	* unregister tabs attributable to a script handle that just left the
280	268	* `serverSettingsTabScripts` payload.
281	269	*
282		- * @since 0.5.1
283		- *
284	270	* @return array[]
285	271	*/
286		-function desktop_mode_build_desktop_settings_tabs_payload() {
287		- $registry = desktop_mode_desktop_settings_tab_registry();
	272	+function openstation_build_desktop_settings_tabs_payload() {
	273	+ $registry = openstation_desktop_settings_tab_registry();
288	274	if ( ! is_array( $registry ) || empty( $registry ) ) {
289	275	return array();
290	276	}
291	277
		@@ -292,9 +278,9 @@
292	278	$out = array();
293	279	foreach ( $registry as $entry ) {
294	280	$handle = (string) $entry['script'];
295	281	$payload = '' !== $handle
296		- ? desktop_mode_resolve_script_payload( $handle )
	282	+ ? openstation_resolve_script_payload( $handle )
297	283	: array(
298	284	'url' => '',
299	285	'before' => array(),
300	286	'after' => array(),
		@@ -300,19 +286,22 @@
300	286	'after' => array(),
301	287	'l10n' => array(),
302	288	'translations' => '',
303	289	);
304		- $out[] = array(
305		- 'id' => (string) $entry['id'],
306		- 'label' => (string) $entry['label'],
307		- 'capability' => (string) $entry['capability'],
308		- 'order' => (int) $entry['order'],
309		- 'scriptUrl' => $payload['url'],
310		- 'scriptHandle' => $handle,
311		- 'scriptBefore' => $payload['before'],
312		- 'scriptAfter' => $payload['after'],
313		- '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'],
314	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 ),
315	304	);
316	305	}
317	306	return $out;
318	307	}