← All changes | includes/registries/window-tabs.php +65 -53 0.9.8 → 1.1.10 View file →

		@@ -1,11 +1,11 @@
1	1	<?php
2	2	/**
3		- * Desktop Mode — Native-window tabs registry.
	3	+ * OpenStation — Native-window tabs registry.
4	4	*
5	5	* Multi-tab native windows are a sister-to-the-window
6	6	* registration: a tab is owned by some window id and its content
7		- * is wrapped in `<wpd-tabpanel>` automatically by the shell. The
	7	+ * is wrapped in `<os-tabpanel>` automatically by the shell. The
8	8	* MAIN_TAB constant reserves the `'main'` value for the window's
9	9	* own `template` callback so plugins can't accidentally collide
10	10	* with the built-in main pane.
11	11	*
		@@ -11,9 +11,9 @@
11	11	*
12	12	* Extracted from `components.php` during the architecture-0.8.1
13	13	* PHP slicing (phase 6).
14	14	*
15		- * @package Desktop_Mode
	15	+ * @package OpenStation
16	16	*/
17	17
18	18	defined( 'ABSPATH' ) || exit;
19	19
		@@ -23,12 +23,12 @@
23	23	* registration's `template` callback, and its label is the
24	24	* window's `main_tab_label` (falling back to the window `title`).
25	25	*
26	26	* Plugins cannot register an additional tab with this value —
27		- * {@see desktop_mode_register_window_tab()} returns
28		- * `desktop_mode_reserved_tab_value` when they try.
	27	+ * {@see openstation_register_window_tab()} returns
	28	+ * `openstation_reserved_tab_value` when they try.
29	29	*/
30		-const DESKTOP_MODE_NATIVE_WINDOW_MAIN_TAB = 'main';
	30	+const OPENSTATION_NATIVE_WINDOW_MAIN_TAB = 'main';
31	31
32	32	/**
33	33	* Register an additional tab on an existing native window.
34	34	*
		@@ -39,23 +39,23 @@
39	39	* alongside it. Cross-plugin extension is supported — a companion
40	40	* plugin can attach a tab to someone else's window.
41	41	*
42	42	* Registering even a single tab turns on the auto-wrap path in
43		- * `desktop_mode_build_native_window_template_html()`: the shell wraps the
44		- * window body in `<wpd-stack>` + `<wpd-tabs>` + `<wpd-tabpanel>`
	43	+ * `openstation_build_native_window_template_html()`: the shell wraps the
	44	+ * window body in `<os-stack>` + `<os-tabs>` + `<os-tabpanel>`
45	45	* elements automatically. Plugin authors no longer hand-write that
46		- * markup — the shell provides it and `<wpd-tabpanel>` auto-swap
	46	+ * markup — the shell provides it and `<os-tabpanel>` auto-swap
47	47	* handles visibility.
48	48	*
49	49	* ```php
50	50	* // Plugin that owns the window declares its own tabs:
51		- * desktop_mode_register_window( 'jorvy', array(
	51	+ * openstation_register_window( 'jorvy', array(
52	52	* 'title' => 'Jorvy',
53	53	* 'main_tab_label' => 'Quotes',
54	54	* 'template' => function () { echo '<p class="quote"></p>'; },
55	55	* 'script' => 'jorvy-main',
56	56	* ) );
57		- * desktop_mode_register_window_tab( 'jorvy', array(
	57	+ * openstation_register_window_tab( 'jorvy', array(
58	58	* 'value' => 'about',
59	59	* 'label' => 'About',
60	60	* 'template' => function () { echo '<p>Marvel quotes, rotated every 10s.</p>'; },
61	61	* ) );
		@@ -60,9 +60,9 @@
60	60	* 'template' => function () { echo '<p>Marvel quotes, rotated every 10s.</p>'; },
61	61	* ) );
62	62	*
63	63	* // A companion plugin attaches a tab to someone else's window:
64		- * desktop_mode_register_window_tab( 'jorvy', array(
	64	+ * openstation_register_window_tab( 'jorvy', array(
65	65	* 'value' => 'stats',
66	66	* 'label' => 'Stats',
67	67	* 'template' => 'jorvy_stats_pane',
68	68	* 'script' => 'jorvy-stats',
		@@ -77,9 +77,9 @@
77	77	* own template tab.
78	78	* @type string $label Display label on the tab strip. Required.
79	79	* @type callable $template Callback that echoes the tab's
80	80	* pane HTML. Wrapped in
81		- * `<wpd-tabpanel for="<value>">` by
	81	+ * `<os-tabpanel for="<value>">` by
82	82	* the shell. Required.
83	83	* @type string $script Optional script handle enqueued
84	84	* when the window is active — useful
85	85	* when a tab needs its own JS module
		@@ -89,17 +89,17 @@
89	89	* window; lower renders earlier.
90	90	* Default 100.
91	91	* @type string[] $capabilities Gate: ALL caps must match. Any
92	92	* missed cap returns
93		- * `WP_Error desktop_mode_capability_denied`.
	93	+ * `WP_Error openstation_capability_denied`.
94	94	* }
95	95	* @return true|WP_Error `true` on success; `WP_Error` otherwise.
96	96	*/
97		-function desktop_mode_register_window_tab( $window_id, $args = array() ) {
	97	+function openstation_register_window_tab( $window_id, $args = array() ) {
98	98	$window_id = sanitize_key( (string) $window_id );
99	99	if ( '' === $window_id ) {
100		- return desktop_mode_registration_error(
101		- 'desktop_mode_missing_window_id',
	100	+ return openstation_registration_error(
	101	+ 'openstation_missing_window_id',
102	102	__( 'Window id is required when registering a tab.', 'desktop-mode' )
103	103	);
104	104	}
105	105
		@@ -110,20 +110,23 @@
110	110	'script' => '',
111	111	'position' => 100,
112	112	'capabilities' => array(),
113	113	);
114		- $args = wp_parse_args( $args, $defaults );
	114	+ $args = wp_parse_args( $args, $defaults );
115	115
116	116	foreach ( (array) $args['capabilities'] as $cap ) {
117	117	if ( ! current_user_can( (string) $cap ) ) {
118		- return desktop_mode_registration_error(
119		- 'desktop_mode_capability_denied',
	118	+ return openstation_registration_error(
	119	+ 'openstation_capability_denied',
120	120	sprintf(
121	121	/* translators: %s: capability slug. */
122	122	__( 'Current user lacks the %s capability required to register this window tab.', 'desktop-mode' ),
123	123	(string) $cap
124	124	),
125		- array( 'capability' => (string) $cap, 'window_id' => $window_id )
	125	+ array(
	126	+ 'capability' => (string) $cap,
	127	+ 'window_id' => $window_id,
	128	+ )
126	129	);
127	130	}
128	131	}
129	132
		@@ -130,52 +133,58 @@
130	133	// Tab values accept both flat slugs ('convert') and a single
131	134	// `vendor/sub-id` namespace ('plugin/convert') so two plugins
132	135	// targeting the same window can ship same-named tabs without
133	136	// stomping each other in the registry. The downstream uses
134		- // (`wpd-tabpanel[for="…"]`, `<wpd-tab value="…">`) all pass the
	137	+ // (`os-tabpanel[for="…"]`, `<os-tab value="…">`) all pass the
135	138	// value through esc_attr and use it as an attribute selector,
136	139	// which tolerates the slash.
137	140	$value_raw = strtolower( trim( (string) $args['value'] ) );
138	141	if ( '' === $value_raw ) {
139		- return desktop_mode_registration_error(
140		- 'desktop_mode_missing_tab_value',
	142	+ return openstation_registration_error(
	143	+ 'openstation_missing_tab_value',
141	144	__( 'Window tab registration requires a non-empty `value`.', 'desktop-mode' ),
142	145	array( 'window_id' => $window_id )
143	146	);
144	147	}
145	148	if ( ! preg_match( '/^[a-z0-9_-]+(\/[a-z0-9_-]+)?$/', $value_raw ) ) {
146		- return desktop_mode_registration_error(
147		- 'desktop_mode_invalid_tab_value',
	149	+ return openstation_registration_error(
	150	+ 'openstation_invalid_tab_value',
148	151	sprintf(
149	152	/* translators: %s: the invalid value. */
150	153	__( 'Window tab `value` "%s" must match /^[a-z0-9_-]+(\/[a-z0-9_-]+)?$/ — lowercase alphanum + hyphen/underscore, with at most one `vendor/sub-id` slash.', 'desktop-mode' ),
151	154	$value_raw
152	155	),
153		- array( 'window_id' => $window_id, 'value' => $value_raw )
	156	+ array(
	157	+ 'window_id' => $window_id,
	158	+ 'value' => $value_raw,
	159	+ )
154	160	);
155	161	}
156	162	$value = $value_raw;
157		- if ( DESKTOP_MODE_NATIVE_WINDOW_MAIN_TAB === $value ) {
158		- return desktop_mode_registration_error(
159		- 'desktop_mode_reserved_tab_value',
	163	+ if ( OPENSTATION_NATIVE_WINDOW_MAIN_TAB === $value ) {
	164	+ return openstation_registration_error(
	165	+ 'openstation_reserved_tab_value',
160	166	sprintf(
161	167	/* translators: %s: the reserved value. */
162	168	__( 'The tab value "%s" is reserved for the window\'s own template tab.', 'desktop-mode' ),
163		- DESKTOP_MODE_NATIVE_WINDOW_MAIN_TAB
	169	+ OPENSTATION_NATIVE_WINDOW_MAIN_TAB
164	170	),
165		- array( 'window_id' => $window_id, 'value' => $value )
	171	+ array(
	172	+ 'window_id' => $window_id,
	173	+ 'value' => $value,
	174	+ )
166	175	);
167	176	}
168	177	if ( '' === (string) $args['label'] ) {
169		- return desktop_mode_registration_error(
170		- 'desktop_mode_missing_label',
	178	+ return openstation_registration_error(
	179	+ 'openstation_missing_label',
171	180	__( 'Window tab registration requires a non-empty `label`.', 'desktop-mode' ),
172	181	array( 'window_id' => $window_id )
173	182	);
174	183	}
175	184	if ( ! is_callable( $args['template'] ) ) {
176		- return desktop_mode_registration_error(
177		- 'desktop_mode_invalid_template',
	185	+ return openstation_registration_error(
	186	+ 'openstation_invalid_template',
178	187	__( 'Window tab registration requires a callable `template` that echoes the pane body.', 'desktop-mode' ),
179	188	array( 'window_id' => $window_id )
180	189	);
181	190	}
		@@ -186,14 +195,14 @@
186	195	'template' => $args['template'],
187	196	'script' => (string) $args['script'],
188	197	'position' => (int) $args['position'],
189	198	);
190		- desktop_mode_desktop_window_tab_registry( $window_id, $value, $entry );
	199	+ openstation_desktop_window_tab_registry( $window_id, $value, $entry );
191	200
192	201	/**
193	202	* Fires after a native window tab is successfully registered.
194	203	*
195		- * Does NOT fire when `desktop_mode_register_window_tab()` returns
	204	+ * Does NOT fire when `openstation_register_window_tab()` returns
196	205	* a `WP_Error`.
197	206	*
198	207	* @param string $window_id The window this tab belongs to.
199	208	* @param string $value The tab value.
		@@ -198,9 +207,9 @@
198	207	* @param string $window_id The window this tab belongs to.
199	208	* @param string $value The tab value.
200	209	* @param array $entry The stored registry entry.
201	210	*/
202		- do_action( 'desktop_mode_window_tab_registered', $window_id, $value, $entry );
	211	+ do_action( 'openstation_window_tab_registered', $window_id, $value, $entry );
203	212
204	213	return true;
205	214	}
206	215
		@@ -217,9 +226,9 @@
217	226	* on the given window).
218	227	* @param array|null $entry Entry to store, or null to just read.
219	228	* @return array|null
220	229	*/
221		-function desktop_mode_desktop_window_tab_registry( $window_id = '', $value = '', $entry = null ) {
	230	+function openstation_desktop_window_tab_registry( $window_id = '', $value = '', $entry = null ) {
222	231	static $store = array();
223	232
224	233	if ( '' === (string) $window_id ) {
225	234	return $store;
		@@ -245,22 +254,22 @@
245	254	* order).
246	255	*
247	256	* Shape per entry: `{ value, label, template, script, is_main, position }`.
248	257	*
249		- * Filterable via `desktop_mode_window_tabs` so a late-loading plugin
	258	+ * Filterable via `openstation_window_tabs` so a late-loading plugin
250	259	* can reorder, hide, or relabel tabs another plugin registered —
251		- * mirrors the `desktop_mode_wallpapers` filter discipline.
	260	+ * mirrors the `openstation_wallpapers` filter discipline.
252	261	*
253	262	* @param string $window_id Window id.
254	263	* @return array[]
255	264	*/
256		-function desktop_mode_get_native_window_tabs( $window_id ) {
257		- $window = desktop_mode_native_window_registry( (string) $window_id );
	265	+function openstation_get_native_window_tabs( $window_id ) {
	266	+ $window = openstation_native_window_registry( (string) $window_id );
258	267	if ( ! is_array( $window ) ) {
259	268	return array();
260	269	}
261	270
262		- $extras = desktop_mode_desktop_window_tab_registry( $window_id );
	271	+ $extras = openstation_desktop_window_tab_registry( $window_id );
263	272	if ( ! is_array( $extras ) ) {
264	273	$extras = array();
265	274	}
266	275
		@@ -268,11 +277,11 @@
268	277	// `main_tab_label` was set during registration.
269	278	$main_label = '' !== (string) $window['main_tab_label']
270	279	? (string) $window['main_tab_label']
271	280	: (string) $window['title'];
272		- $tabs = array(
	281	+ $tabs = array(
273	282	array(
274		- 'value' => DESKTOP_MODE_NATIVE_WINDOW_MAIN_TAB,
	283	+ 'value' => OPENSTATION_NATIVE_WINDOW_MAIN_TAB,
275	284	'label' => $main_label,
276	285	'template' => $window['template'],
277	286	'script' => '',
278	287	'is_main' => true,
		@@ -283,14 +292,17 @@
283	292	// Additional tabs sorted by position. Values are trusted — they
284	293	// were validated against /^[a-z0-9_-]+(\/[a-z0-9_-]+)?$/ at
285	294	// registration time (sanitize_key would strip the namespace slash).
286	295	$sorted = array_values( $extras );
287		- usort( $sorted, static function ( $a, $b ) {
288		- if ( $a['position'] === $b['position'] ) {
289		- return 0;
	296	+ usort(
	297	+ $sorted,
	298	+ static function ( $a, $b ) {
	299	+ if ( $a['position'] === $b['position'] ) {
	300	+ return 0;
	301	+ }
	302	+ return $a['position'] < $b['position'] ? -1 : 1;
290	303	}
291		- return $a['position'] < $b['position'] ? -1 : 1;
292		- } );
	304	+ );
293	305	foreach ( $sorted as $tab ) {
294	306	$tabs[] = array(
295	307	'value' => $tab['value'],
296	308	'label' => $tab['label'],
		@@ -312,7 +324,7 @@
312	324	*
313	325	* @param array[] $tabs Ordered tab descriptors.
314	326	* @param string $window_id Window id.
315	327	*/
316		- $filtered = apply_filters( 'desktop_mode_window_tabs', $tabs, $window_id );
	328	+ $filtered = apply_filters( 'openstation_window_tabs', $tabs, $window_id );
317	329	return is_array( $filtered ) ? $filtered : $tabs;
318	330	}