← All changes | includes/registries/wallpapers.php +78 -79 0.9.6 → 1.1.10 View file →

		@@ -1,11 +1,11 @@
1	1	<?php
2	2	/**
3		- * Desktop Mode — Wallpapers registry.
	3	+ * OpenStation — Wallpapers registry.
4	4	*
5	5	* Server-side registration API + payload builder + asset enqueue
6	6	* for the desktop wallpaper picker. Wallpaper definitions live
7		- * on `window.desktopModeWallpapers[ id ]` (set by the plugin's
	7	+ * on `window.openStationWallpapers[ id ]` (set by the plugin's
8	8	* own JS); this module is the PHP side that announces them to
9	9	* the shell and ships their script handles into the boot
10	10	* payload.
11	11	*
		@@ -12,10 +12,9 @@
12	12	* Extracted from `components.php` during the architecture-0.8.1
13	13	* PHP slicing (phase 6). Behaviour, function names, filter
14	14	* contracts, and error codes all unchanged.
15	15	*
16		- * @package Desktop_Mode
17		- * @since 0.8.1
	16	+ * @package OpenStation
18	17	*/
19	18
20	19	defined( 'ABSPATH' ) || exit;
21	20
		@@ -20,12 +19,12 @@
20	19	defined( 'ABSPATH' ) || exit;
21	20
22	21	/**
23	22	* Register a server-side desktop wallpaper. Symmetrical to
24		- * {@see desktop_mode_register_widget()}. The plugin's JS side
	23	+ * {@see openstation_register_widget()}. The plugin's JS side
25	24	* publishes the full `WallpaperDef` (with mount / resolveValue /
26	25	* renderEditor callbacks as appropriate) on
27		- * `window.desktopModeWallpapers[ <id> ]`; the shell loads the
	26	+ * `window.openStationWallpapers[ <id> ]`; the shell loads the
28	27	* declared script, reads that global, and registers the def via
29	28	* the normal wallpaper registry. Deactivation unregisters the
30	29	* def and re-applies the current selection (which falls back to
31	30	* a built-in if the user's active wallpaper was the one leaving).
		@@ -32,9 +31,9 @@
32	31	*
33	32	* Example:
34	33	*
35	34	* ```php
36		- * desktop_mode_register_wallpaper( 'myplugin/snow', array(
	35	+ * openstation_register_wallpaper( 'myplugin/snow', array(
37	36	* 'label' => __( 'Snow', 'my-plugin' ),
38	37	* 'preview' => 'linear-gradient(#fff, #ddd)',
39	38	* 'type' => 'canvas',
40	39	* 'script' => 'my-plugin-snow-wallpaper',
		@@ -42,10 +41,10 @@
42	41	* ```
43	42	*
44	43	* ```js
45	44	* // Inside my-plugin-snow-wallpaper.js
46		- * window.desktopModeWallpapers = window.desktopModeWallpapers || {};
47		- * window.desktopModeWallpapers[ 'myplugin/snow' ] = {
	45	+ * window.openStationWallpapers = window.openStationWallpapers || {};
	46	+ * window.openStationWallpapers[ 'myplugin/snow' ] = {
48	47	* id: 'myplugin/snow',
49	48	* label: 'Snow',
50	49	* type: 'canvas',
51	50	* preview: 'linear-gradient(#fff, #ddd)',
		@@ -53,15 +52,10 @@
53	52	* mount: function ( container, ctx ) { return function () {}; },
54	53	* };
55	54	* ```
56	55	*
57		- * @since 0.8.1
58		- * @since 0.8.1 Returns `WP_Error` on validation failure instead of
59		- * silent `false`. Legacy `if ( $result )` callers remain
60		- * correct because `WP_Error` is truthy.
61		- *
62	56	* @param string $id Wallpaper id. For canvas wallpapers this must
63		- * match the `window.desktopModeWallpapers[<id>]`
	57	+ * match the `window.openStationWallpapers[<id>]`
64	58	* key the plugin's JS publishes.
65	59	* @param array $args {
66	60	* @type string $label Picker label. Required.
67	61	* @type string $preview CSS value rendered in the picker
		@@ -82,20 +76,20 @@
82	76	* @type string $description Plain-text description shown in OS
83	77	* Settings when the wallpaper is the
84	78	* active selection — what it is, where
85	79	* its data comes from, the story behind
86		- * it. Optional. Since 0.9.4.
	80	+ * it. Optional.
87	81	* @type string[] $capabilities Gate: ALL caps must match. Any
88	82	* missed cap returns
89		- * `WP_Error desktop_mode_capability_denied`.
	83	+ * `WP_Error openstation_capability_denied`.
90	84	* }
91	85	* @return true|WP_Error `true` on success; `WP_Error` otherwise.
92	86	*/
93		-function desktop_mode_register_wallpaper( $id, $args = array() ) {
	87	+function openstation_register_wallpaper( $id, $args = array() ) {
94	88	$id = (string) $id;
95	89	if ( '' === $id ) {
96		- return desktop_mode_registration_error(
97		- 'desktop_mode_missing_id',
	90	+ return openstation_registration_error(
	91	+ 'openstation_missing_id',
98	92	__( 'Wallpaper id is required.', 'desktop-mode' )
99	93	);
100	94	}
101	95
		@@ -107,26 +101,29 @@
107	101	'script' => '',
108	102	'description' => '',
109	103	'capabilities' => array(),
110	104	);
111		- $args = wp_parse_args( $args, $defaults );
	105	+ $args = wp_parse_args( $args, $defaults );
112	106
113	107	foreach ( (array) $args['capabilities'] as $cap ) {
114	108	if ( ! current_user_can( (string) $cap ) ) {
115		- return desktop_mode_registration_error(
116		- 'desktop_mode_capability_denied',
	109	+ return openstation_registration_error(
	110	+ 'openstation_capability_denied',
117	111	sprintf(
118	112	/* translators: %s: capability slug. */
119	113	__( 'Current user lacks the %s capability required to register this wallpaper.', 'desktop-mode' ),
120	114	(string) $cap
121	115	),
122		- array( 'capability' => (string) $cap, 'id' => $id )
	116	+ array(
	117	+ 'capability' => (string) $cap,
	118	+ 'id' => $id,
	119	+ )
123	120	);
124	121	}
125	122	}
126	123	if ( '' === (string) $args['label'] ) {
127		- return desktop_mode_registration_error(
128		- 'desktop_mode_missing_label',
	124	+ return openstation_registration_error(
	125	+ 'openstation_missing_label',
129	126	__( 'Wallpaper registration requires a non-empty `label`.', 'desktop-mode' ),
130	127	array( 'id' => $id )
131	128	);
132	129	}
		@@ -137,10 +134,10 @@
137	134	// `mount` callback is published on the JS global by that
138	135	// script). CSS wallpapers can skip the script — the shell can
139	136	// render from the `value` / `preview` string alone.
140	137	if ( 'canvas' === $type && '' === (string) $args['script'] ) {
141		- return desktop_mode_registration_error(
142		- 'desktop_mode_missing_script',
	138	+ return openstation_registration_error(
	139	+ 'openstation_missing_script',
143	140	__( 'Canvas wallpaper registration requires a `script` handle that publishes the def.', 'desktop-mode' ),
144	141	array( 'id' => $id )
145	142	);
146	143	}
		@@ -155,9 +152,19 @@
155	152	}
156	153
157	154	$entry = array(
158	155	'id' => $id,
159		- 'label' => (string) $args['label'],
	156	+ // Plain text by contract, same as `description` below. The
	157	+ // shell paints labels through the `html` tagged template, whose
	158	+ // text slots build DOM with `createTextNode()` — never
	159	+ // `innerHTML` — so a label cannot become markup downstream.
	160	+ //
	161	+ // Note this STRIPS rather than ESCAPES, and that distinction is
	162	+ // load-bearing: `esc_html()` here would encode `&` in a
	163	+ // perfectly ordinary label ("Black & White") and the text node
	164	+ // would then render the entity literally as `&amp;`. Escaping
	165	+ // belongs at an HTML boundary; there isn't one on this path.
	166	+ 'label' => sanitize_text_field( (string) $args['label'] ),
160	167	'preview' => (string) $args['preview'],
161	168	'type' => $type,
162	169	'value' => $value,
163	170	'script' => (string) $args['script'],
		@@ -164,22 +171,20 @@
164	171	// Plain text by contract — the shell renders it as text, never
165	172	// as HTML, so strip tags here rather than trusting every caller.
166	173	'description' => sanitize_textarea_field( (string) $args['description'] ),
167	174	);
168		- desktop_mode_desktop_wallpaper_registry( $id, $entry );
	175	+ openstation_desktop_wallpaper_registry( $id, $entry );
169	176
170	177	/**
171	178	* Fires after a desktop wallpaper is successfully registered.
172	179	*
173		- * Does NOT fire when `desktop_mode_register_wallpaper()` returns a
	180	+ * Does NOT fire when `openstation_register_wallpaper()` returns a
174	181	* `WP_Error`.
175	182	*
176		- * @since 0.8.1
177		- *
178	183	* @param string $id The wallpaper id.
179	184	* @param array $entry The stored registry entry.
180	185	*/
181		- do_action( 'desktop_mode_wallpaper_registered', $id, $entry );
	186	+ do_action( 'openstation_wallpaper_registered', $id, $entry );
182	187
183	188	return true;
184	189	}
185	190
		@@ -184,15 +189,14 @@
184	189	}
185	190
186	191	/**
187	192	* Internal module-level registry for wallpapers registered via
188		- * {@see desktop_mode_register_wallpaper()}. Same static-store
	193	+ * {@see openstation_register_wallpaper()}. Same static-store
189	194	* pattern as the widget + native-window registries.
190	195	*
191		- * @since 0.8.1
192	196	* @internal
193	197	*/
194		-function desktop_mode_desktop_wallpaper_registry( $id = '', $entry = null ) {
	198	+function openstation_desktop_wallpaper_registry( $id = '', $entry = null ) {
195	199	static $store = array();
196	200
197	201	if ( '' === (string) $id ) {
198	202	return $store;
		@@ -207,28 +211,24 @@
207	211	* Build the wallpaper list for the shell payload. Only metadata +
208	212	* the resolved script URL cross the wire; the plugin's mount
209	213	* callback is announced via the JS global the script sets up.
210	214	*
211		- * @since 0.8.1
212		- *
213	215	* @return array[]
214	216	*/
215		-function desktop_mode_build_desktop_wallpapers_payload() {
216		- $registry = desktop_mode_desktop_wallpaper_registry();
	217	+function openstation_build_desktop_wallpapers_payload() {
	218	+ $registry = openstation_desktop_wallpaper_registry();
217	219	if ( ! is_array( $registry ) || empty( $registry ) ) {
218	220	return array();
219	221	}
220	222	/**
221	223	* Filters the server-declared wallpaper list before it ships to
222		- * the shell. Mirrors the JS-side `desktop-mode.wallpapers` filter
	224	+ * the shell. Mirrors the JS-side `os.wallpapers` filter
223	225	* so plugins can rearrange, hide, or override entries at boot
224	226	* without round-tripping through the JS registry.
225	227	*
226		- * @since 0.8.1
227		- *
228	228	* @param array[] $registry The registered wallpaper entries.
229	229	*/
230		- $registry = apply_filters( 'desktop_mode_wallpapers', $registry );
	230	+ $registry = apply_filters( 'openstation_wallpapers', $registry );
231	231	if ( ! is_array( $registry ) ) {
232	232	return array();
233	233	}
234	234	$out = array();
		@@ -236,22 +236,25 @@
236	236	if ( ! is_array( $entry ) || empty( $entry['id'] ) ) {
237	237	continue;
238	238	}
239	239	$handle = isset( $entry['script'] ) ? (string) $entry['script'] : '';
240		- $payload = desktop_mode_resolve_script_payload( $handle );
241		- $out[] = array(
242		- 'id' => (string) $entry['id'],
243		- 'label' => isset( $entry['label'] ) ? (string) $entry['label'] : '',
244		- 'preview' => isset( $entry['preview'] ) ? (string) $entry['preview'] : '',
245		- 'type' => isset( $entry['type'] ) ? (string) $entry['type'] : 'canvas',
246		- 'value' => isset( $entry['value'] ) ? (string) $entry['value'] : '',
247		- 'description' => isset( $entry['description'] ) ? (string) $entry['description'] : '',
248		- 'scriptUrl' => $payload['url'],
249		- 'scriptHandle' => $handle,
250		- 'scriptBefore' => $payload['before'],
251		- 'scriptAfter' => $payload['after'],
252		- 'scriptL10n' => $payload['l10n'],
	240	+ $payload = openstation_resolve_script_payload( $handle );
	241	+ $out[] = array(
	242	+ 'id' => (string) $entry['id'],
	243	+ 'label' => isset( $entry['label'] ) ? (string) $entry['label'] : '',
	244	+ 'preview' => isset( $entry['preview'] ) ? (string) $entry['preview'] : '',
	245	+ 'type' => isset( $entry['type'] ) ? (string) $entry['type'] : 'canvas',
	246	+ 'value' => isset( $entry['value'] ) ? (string) $entry['value'] : '',
	247	+ 'description' => isset( $entry['description'] ) ? (string) $entry['description'] : '',
	248	+ 'scriptUrl' => $payload['url'],
	249	+ 'scriptHandle' => $handle,
	250	+ 'scriptBefore' => $payload['before'],
	251	+ 'scriptAfter' => $payload['after'],
	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	}
256	259	return $out;
257	260	}
		@@ -256,27 +259,23 @@
256	259	return $out;
257	260	}
258	261
259	262
260		-/**
261		- * Enqueue plugin-registered wallpaper scripts on the shell page
262		- * so wallpapers active at boot time have their defs available
263		- * without any dynamic-load roundtrip.
	263	+/*
	264	+ * Wallpaper scripts are NOT enqueued here, and that is deliberate.
264	265	*
265		- * @since 0.8.1
	266	+ * A canvas wallpaper's bundle IS the wallpaper — Living Tree is 58 KB
	267	+ * of PixiJS scene, Snow is 42 KB — and this file used to
	268	+ * `wp_enqueue_script()` every registered one on every admin page, so
	269	+ * that every user downloaded and parsed every wallpaper in the
	270	+ * install including the ones they were not wearing. The metadata in
	271	+ * the boot payload (label, preview swatch, description) is enough for
	272	+ * the shell to register a stub and paint a picker tile without any of
	273	+ * it.
	274	+ *
	275	+ * The bundle arrives when something needs the callbacks: the shell
	276	+ * hydrates the user's ACTIVE wallpaper during the boot sync, and the
	277	+ * wallpaper picker hydrates the rest when it opens. See
	278	+ * `src/wallpapers/lazy.ts`. `scriptUrl` in the payload (built above)
	279	+ * is what makes that possible; nothing else on the PHP side is
	280	+ * involved.
266	281	*/
267		-function desktop_mode_enqueue_desktop_wallpaper_scripts() {
268		- if ( ! desktop_mode_is_enabled() || desktop_mode_is_chromeless_request() || desktop_mode_is_classic_request() ) {
269		- return;
270		- }
271		- $registry = desktop_mode_desktop_wallpaper_registry();
272		- if ( ! is_array( $registry ) ) {
273		- return;
274		- }
275		- foreach ( $registry as $entry ) {
276		- if ( ! empty( $entry['script'] ) ) {
277		- wp_enqueue_script( $entry['script'] );
278		- }
279		- }
280		-}
281		-add_action( 'admin_enqueue_scripts', 'desktop_mode_enqueue_desktop_wallpaper_scripts', 20 );
282		-