← All changes | includes/registries/icons.php +63 -53 0.9.8 → 1.1.10 View file →

		@@ -1,15 +1,19 @@
1	1	<?php
2	2	/**
3		- * Desktop Mode — Desktop-icons registry.
	3	+ * OpenStation — Desktop-icons registry.
4	4	*
5	5	* Owns the registration API + payload builder for the wallpaper-
6		- * surface app icons (`wp.desktop.icons`). The dock has its own
	6	+ * surface app icons (`wp.os.icons`). The dock has its own
7	7	* rail; this is the second surface — clickable shortcuts that
8	8	* sit on the desktop wallpaper itself, registered via
9		- * `desktop_mode_register_icon()` and rendered by
	9	+ * `openstation_register_icon()` and rendered by
10	10	* `src/desktop-icons.ts`.
11	11	*
	12	+ * Not to be confused with `includes/wp-icon-registry.php`, which hands our
	13	+ * eleven pieces of artwork to WordPress's own icon registry for use with
	14	+ * `wp_get_icon()`. This file is about a surface of the desktop.
	15	+ *
12	16	* Extracted from the 2,101-LOC `components.php` during the
13	17	* architecture-0.8.1 PHP slicing (phase 6). Behaviour is
14	18	* unchanged: every function name, every WP filter, every error
15	19	* code is identical. PHP looks function references up by name at
		@@ -14,9 +18,9 @@
14	18	* unchanged: every function name, every WP filter, every error
15	19	* code is identical. PHP looks function references up by name at
16	20	* hook-fire time, so existing call sites resolve from any module.
17	21	*
18		- * @package Desktop_Mode
	22	+ * @package OpenStation
19	23	*/
20	24
21	25	defined( 'ABSPATH' ) || exit;
22	26
		@@ -34,10 +38,10 @@
34	38	*
35	39	* Example — the classic Jorvy recipe:
36	40	*
37	41	* ```php
38		- * desktop_mode_register_window( 'jorvy', array( …window args… ) );
39		- * desktop_mode_register_icon( 'jorvy', array(
	42	+ * openstation_register_window( 'jorvy', array( …window args… ) );
	43	+ * openstation_register_icon( 'jorvy', array(
40	44	* 'title' => __( 'Jorvy', 'jorvy' ),
41	45	* 'icon' => 'dashicons-star-filled',
42	46	* 'window' => 'jorvy',
43	47	* 'position' => 10,
		@@ -62,9 +66,9 @@
62	66	* URI and routes the result through the
63	67	* same sanitizer as `icon`. Wins over
64	68	* `icon` when both are supplied. Markup
65	69	* containing a `<script>` tag is rejected
66		- * with `desktop_mode_invalid_icon_svg`.
	70	+ * with `openstation_invalid_icon_svg`.
67	71	* @type string $window Id of a registered native window to
68	72	* open on click. Mutually exclusive
69	73	* with `url`.
70	74	* @type string $url URL to open on click (admin URLs
		@@ -80,17 +84,17 @@
80	84	* shortcuts like "My WordPress".
81	85	* Default `false`.
82	86	* @type string[] $capabilities Gate: ALL caps must match. Any
83	87	* missed cap returns
84		- * `WP_Error desktop_mode_capability_denied`.
	88	+ * `WP_Error openstation_capability_denied`.
85	89	* }
86	90	* @return true|WP_Error `true` on success; `WP_Error` otherwise.
87	91	*/
88		-function desktop_mode_register_icon( $id, $args = array() ) {
	92	+function openstation_register_icon( $id, $args = array() ) {
89	93	$id = sanitize_key( (string) $id );
90	94	if ( '' === $id ) {
91		- return desktop_mode_registration_error(
92		- 'desktop_mode_missing_id',
	95	+ return openstation_registration_error(
	96	+ 'openstation_missing_id',
93	97	__( 'Desktop icon id is required and must be a valid slug.', 'desktop-mode' )
94	98	);
95	99	}
96	100
		@@ -103,9 +107,9 @@
103	107	'position' => 100,
104	108	'pinned' => false,
105	109	'capabilities' => array(),
106	110	);
107		- $args = wp_parse_args( $args, $defaults );
	111	+ $args = wp_parse_args( $args, $defaults );
108	112
109	113	$svg = trim( (string) $args['icon_svg'] );
110	114	if ( '' !== $svg ) {
111	115	// Reject markup that contains a script tag outright. The data
		@@ -112,17 +116,17 @@
112	116	// URI is consumed via `<img src=…>` in the browser (which
113	117	// sandboxes scripts inside SVG), but defence-in-depth catches
114	118	// callers who paste an SVG harvested from an untrusted source.
115	119	if ( false !== stripos( $svg, '<script' ) ) {
116		- return desktop_mode_registration_error(
117		- 'desktop_mode_invalid_icon_svg',
	120	+ return openstation_registration_error(
	121	+ 'openstation_invalid_icon_svg',
118	122	__( 'Desktop icon `icon_svg` must not contain a <script> tag.', 'desktop-mode' ),
119	123	array( 'id' => $id )
120	124	);
121	125	}
122	126	if ( 0 !== stripos( ltrim( $svg ), '<svg' ) ) {
123		- return desktop_mode_registration_error(
124		- 'desktop_mode_invalid_icon_svg',
	127	+ return openstation_registration_error(
	128	+ 'openstation_invalid_icon_svg',
125	129	__( 'Desktop icon `icon_svg` must start with a <svg> root element.', 'desktop-mode' ),
126	130	array( 'id' => $id )
127	131	);
128	132	}
		@@ -130,23 +134,26 @@
130	134	}
131	135
132	136	foreach ( (array) $args['capabilities'] as $cap ) {
133	137	if ( ! current_user_can( (string) $cap ) ) {
134		- return desktop_mode_registration_error(
135		- 'desktop_mode_capability_denied',
	138	+ return openstation_registration_error(
	139	+ 'openstation_capability_denied',
136	140	sprintf(
137	141	/* translators: %s: capability slug. */
138	142	__( 'Current user lacks the %s capability required to register this desktop icon.', 'desktop-mode' ),
139	143	(string) $cap
140	144	),
141		- array( 'capability' => (string) $cap, 'id' => $id )
	145	+ array(
	146	+ 'capability' => (string) $cap,
	147	+ 'id' => $id,
	148	+ )
142	149	);
143	150	}
144	151	}
145	152
146	153	if ( '' === (string) $args['title'] ) {
147		- return desktop_mode_registration_error(
148		- 'desktop_mode_missing_title',
	154	+ return openstation_registration_error(
	155	+ 'openstation_missing_title',
149	156	__( 'Desktop icon registration requires a non-empty `title`.', 'desktop-mode' ),
150	157	array( 'id' => $id )
151	158	);
152	159	}
		@@ -153,17 +160,17 @@
153	160
154	161	$window = sanitize_key( (string) $args['window'] );
155	162	$url = (string) $args['url'];
156	163	if ( '' !== $window && '' !== $url ) {
157		- return desktop_mode_registration_error(
158		- 'desktop_mode_conflicting_target',
	164	+ return openstation_registration_error(
	165	+ 'openstation_conflicting_target',
159	166	__( 'Desktop icon cannot declare both `window` and `url`; pick one target.', 'desktop-mode' ),
160	167	array( 'id' => $id )
161	168	);
162	169	}
163	170	if ( '' === $window && '' === $url ) {
164		- return desktop_mode_registration_error(
165		- 'desktop_mode_missing_target',
	171	+ return openstation_registration_error(
	172	+ 'openstation_missing_target',
166	173	__( 'Desktop icon must declare a `window` id or a `url` target.', 'desktop-mode' ),
167	174	array( 'id' => $id )
168	175	);
169	176	}
		@@ -172,10 +179,10 @@
172	179	// desktop window; off-site URLs open in a new browser tab at
173	180	// click time (shell decides).
174	181	$url = esc_url_raw( $url, array( 'http', 'https' ) );
175	182	if ( '' === $url ) {
176		- return desktop_mode_registration_error(
177		- 'desktop_mode_invalid_url',
	183	+ return openstation_registration_error(
	184	+ 'openstation_invalid_url',
178	185	__( 'Desktop icon `url` must be a valid http(s) URL.', 'desktop-mode' ),
179	186	array( 'id' => $id )
180	187	);
181	188	}
		@@ -183,20 +190,20 @@
183	190
184	191	$entry = array(
185	192	'id' => $id,
186	193	'title' => (string) $args['title'],
187		- 'icon' => desktop_mode_sanitize_dock_icon( (string) $args['icon'] ),
	194	+ 'icon' => openstation_sanitize_dock_icon( (string) $args['icon'] ),
188	195	'window' => $window,
189	196	'url' => $url,
190	197	'position' => (int) $args['position'],
191	198	'pinned' => (bool) $args['pinned'],
192	199	);
193		- desktop_mode_desktop_icon_registry( $id, $entry );
	200	+ openstation_desktop_icon_registry( $id, $entry );
194	201
195	202	/**
196	203	* Fires after a desktop icon is successfully registered.
197	204	*
198		- * Does NOT fire when `desktop_mode_register_icon()` returns a
	205	+ * Does NOT fire when `openstation_register_icon()` returns a
199	206	* `WP_Error`.
200	207	*
201	208	* @param string $id The icon id.
202	209	* @param array $entry The stored registry entry (id, title,
		@@ -201,9 +208,9 @@
201	208	* @param string $id The icon id.
202	209	* @param array $entry The stored registry entry (id, title,
203	210	* icon, window, url, position, pinned).
204	211	*/
205		- do_action( 'desktop_mode_icon_registered', $id, $entry );
	212	+ do_action( 'openstation_icon_registered', $id, $entry );
206	213
207	214	return true;
208	215	}
209	216
		@@ -208,14 +215,14 @@
208	215	}
209	216
210	217	/**
211	218	* Internal module-level registry for desktop icons registered via
212		- * {@see desktop_mode_register_icon()}. Same static-store pattern as
	219	+ * {@see openstation_register_icon()}. Same static-store pattern as
213	220	* the widget + native-window + wallpaper registries.
214	221	*
215	222	* @internal
216	223	*/
217		-function desktop_mode_desktop_icon_registry( $id = '', $entry = null ) {
	224	+function openstation_desktop_icon_registry( $id = '', $entry = null ) {
218	225	static $store = array();
219	226
220	227	if ( '' === (string) $id ) {
221	228	return $store;
		@@ -220,9 +227,9 @@
220	227	if ( '' === (string) $id ) {
221	228	return $store;
222	229	}
223	230	// Sentinel write: passing the literal string `__unset__` removes
224		- // the entry. Used by `desktop_mode_unregister_icon()` and by
	231	+ // the entry. Used by `openstation_unregister_icon()` and by
225	232	// PHPUnit teardowns; lets us clear test-only registrations
226	233	// without exposing the static `$store` directly.
227	234	if ( '__unset__' === $entry ) {
228	235	unset( $store[ $id ] );
		@@ -235,34 +242,34 @@
235	242	}
236	243
237	244	/**
238	245	* Remove a previously registered desktop icon from the static
239		- * registry. Mirror of `desktop_mode_register_icon()` — handy for
	246	+ * registry. Mirror of `openstation_register_icon()` — handy for
240	247	* plugins that register icons conditionally and need to drop them
241	248	* mid-request, and for PHPUnit teardowns that shouldn't leak
242	249	* registrations into other tests.
243	250	*
244		- * @param string $id Icon id passed to `desktop_mode_register_icon()`.
	251	+ * @param string $id Icon id passed to `openstation_register_icon()`.
245	252	* @return void
246	253	*/
247		-function desktop_mode_unregister_icon( $id ) {
	254	+function openstation_unregister_icon( $id ) {
248	255	$id = sanitize_key( (string) $id );
249	256	if ( '' === $id ) {
250	257	return;
251	258	}
252		- desktop_mode_desktop_icon_registry( $id, '__unset__' );
	259	+ openstation_desktop_icon_registry( $id, '__unset__' );
253	260	}
254	261
255	262	/**
256	263	* Build the desktop-icon list for the shell payload. Applies a
257		- * `desktop_mode_icons` filter so plugins can hide / reorder / rename
	264	+ * `openstation_icons` filter so plugins can hide / reorder / rename
258	265	* entries registered by others — mirrors the wallpaper payload
259	266	* builder's filter discipline.
260	267	*
261	268	* @return array[]
262	269	*/
263		-function desktop_mode_build_desktop_icons_payload() {
264		- $registry = desktop_mode_desktop_icon_registry();
	270	+function openstation_build_desktop_icons_payload() {
	271	+ $registry = openstation_desktop_icon_registry();
265	272	if ( ! is_array( $registry ) || empty( $registry ) ) {
266	273	return array();
267	274	}
268	275
		@@ -268,14 +275,14 @@
268	275
269	276	/**
270	277	* Filters the full desktop-icon registry before it ships to the
271	278	* shell. Each entry is the shape stored by
272		- * `desktop_mode_register_icon()` (`id`, `title`, `icon`, `window`,
	279	+ * `openstation_register_icon()` (`id`, `title`, `icon`, `window`,
273	280	* `url`, `position`, `pinned`). Return a reordered / filtered array.
274	281	*
275	282	* @param array[] $registry The registered icon entries.
276	283	*/
277		- $registry = apply_filters( 'desktop_mode_icons', $registry );
	284	+ $registry = apply_filters( 'openstation_icons', $registry );
278	285	if ( ! is_array( $registry ) ) {
279	286	return array();
280	287	}
281	288
		@@ -295,18 +302,21 @@
295	302	);
296	303	}
297	304
298	305	// Pinned icons first; then by position. Ties break on insertion order.
299		- usort( $out, static function ( $a, $b ) {
300		- $ap = ! empty( $a['pinned'] ) ? 0 : 1;
301		- $bp = ! empty( $b['pinned'] ) ? 0 : 1;
302		- if ( $ap !== $bp ) {
303		- return $ap - $bp;
	306	+ usort(
	307	+ $out,
	308	+ static function ( $a, $b ) {
	309	+ $ap = ! empty( $a['pinned'] ) ? 0 : 1;
	310	+ $bp = ! empty( $b['pinned'] ) ? 0 : 1;
	311	+ if ( $ap !== $bp ) {
	312	+ return $ap - $bp;
	313	+ }
	314	+ if ( $a['position'] === $b['position'] ) {
	315	+ return 0;
	316	+ }
	317	+ return $a['position'] < $b['position'] ? -1 : 1;
304	318	}
305		- if ( $a['position'] === $b['position'] ) {
306		- return 0;
307		- }
308		- return $a['position'] < $b['position'] ? -1 : 1;
309		- } );
	319	+ );
310	320
311	321	return $out;
312	322	}