← All changes | includes/registries/wallpapers.php +79 -63 0.9.8 → 1.1.12 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,9 +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
	16	+ * @package OpenStation
17	17	*/
18	18
19	19	defined( 'ABSPATH' ) || exit;
20	20
		@@ -19,12 +19,12 @@
19	19	defined( 'ABSPATH' ) || exit;
20	20
21	21	/**
22	22	* Register a server-side desktop wallpaper. Symmetrical to
23		- * {@see desktop_mode_register_widget()}. The plugin's JS side
	23	+ * {@see openstation_register_widget()}. The plugin's JS side
24	24	* publishes the full `WallpaperDef` (with mount / resolveValue /
25	25	* renderEditor callbacks as appropriate) on
26		- * `window.desktopModeWallpapers[ <id> ]`; the shell loads the
	26	+ * `window.openStationWallpapers[ <id> ]`; the shell loads the
27	27	* declared script, reads that global, and registers the def via
28	28	* the normal wallpaper registry. Deactivation unregisters the
29	29	* def and re-applies the current selection (which falls back to
30	30	* a built-in if the user's active wallpaper was the one leaving).
		@@ -31,9 +31,9 @@
31	31	*
32	32	* Example:
33	33	*
34	34	* ```php
35		- * desktop_mode_register_wallpaper( 'myplugin/snow', array(
	35	+ * openstation_register_wallpaper( 'myplugin/snow', array(
36	36	* 'label' => __( 'Snow', 'my-plugin' ),
37	37	* 'preview' => 'linear-gradient(#fff, #ddd)',
38	38	* 'type' => 'canvas',
39	39	* 'script' => 'my-plugin-snow-wallpaper',
		@@ -41,10 +41,10 @@
41	41	* ```
42	42	*
43	43	* ```js
44	44	* // Inside my-plugin-snow-wallpaper.js
45		- * window.desktopModeWallpapers = window.desktopModeWallpapers || {};
46		- * window.desktopModeWallpapers[ 'myplugin/snow' ] = {
	45	+ * window.openStationWallpapers = window.openStationWallpapers || {};
	46	+ * window.openStationWallpapers[ 'myplugin/snow' ] = {
47	47	* id: 'myplugin/snow',
48	48	* label: 'Snow',
49	49	* type: 'canvas',
50	50	* preview: 'linear-gradient(#fff, #ddd)',
		@@ -53,9 +53,9 @@
53	53	* };
54	54	* ```
55	55	*
56	56	* @param string $id Wallpaper id. For canvas wallpapers this must
57		- * match the `window.desktopModeWallpapers[<id>]`
	57	+ * match the `window.openStationWallpapers[<id>]`
58	58	* key the plugin's JS publishes.
59	59	* @param array $args {
60	60	* @type string $label Picker label. Required.
61	61	* @type string $preview CSS value rendered in the picker
		@@ -77,19 +77,26 @@
77	77	* Settings when the wallpaper is the
78	78	* active selection — what it is, where
79	79	* its data comes from, the story behind
80	80	* it. Optional.
	81	+ * @type string $tone 'light' | 'dark'. Whether the desk
	82	+ * paints its icons and labels in
	83	+ * Starlight or in Void. Optional;
	84	+ * unset reads as 'dark'. Declare
	85	+ * 'light' if a user would call your
	86	+ * surface pale. See
	87	+ * docs/desktop-themes.md.
81	88	* @type string[] $capabilities Gate: ALL caps must match. Any
82	89	* missed cap returns
83		- * `WP_Error desktop_mode_capability_denied`.
	90	+ * `WP_Error openstation_capability_denied`.
84	91	* }
85	92	* @return true|WP_Error `true` on success; `WP_Error` otherwise.
86	93	*/
87		-function desktop_mode_register_wallpaper( $id, $args = array() ) {
	94	+function openstation_register_wallpaper( $id, $args = array() ) {
88	95	$id = (string) $id;
89	96	if ( '' === $id ) {
90		- return desktop_mode_registration_error(
91		- 'desktop_mode_missing_id',
	97	+ return openstation_registration_error(
	98	+ 'openstation_missing_id',
92	99	__( 'Wallpaper id is required.', 'desktop-mode' )
93	100	);
94	101	}
95	102
		@@ -99,28 +106,32 @@
99	106	'type' => 'canvas',
100	107	'value' => '',
101	108	'script' => '',
102	109	'description' => '',
	110	+ 'tone' => '',
103	111	'capabilities' => array(),
104	112	);
105		- $args = wp_parse_args( $args, $defaults );
	113	+ $args = wp_parse_args( $args, $defaults );
106	114
107	115	foreach ( (array) $args['capabilities'] as $cap ) {
108	116	if ( ! current_user_can( (string) $cap ) ) {
109		- return desktop_mode_registration_error(
110		- 'desktop_mode_capability_denied',
	117	+ return openstation_registration_error(
	118	+ 'openstation_capability_denied',
111	119	sprintf(
112	120	/* translators: %s: capability slug. */
113	121	__( 'Current user lacks the %s capability required to register this wallpaper.', 'desktop-mode' ),
114	122	(string) $cap
115	123	),
116		- array( 'capability' => (string) $cap, 'id' => $id )
	124	+ array(
	125	+ 'capability' => (string) $cap,
	126	+ 'id' => $id,
	127	+ )
117	128	);
118	129	}
119	130	}
120	131	if ( '' === (string) $args['label'] ) {
121		- return desktop_mode_registration_error(
122		- 'desktop_mode_missing_label',
	132	+ return openstation_registration_error(
	133	+ 'openstation_missing_label',
123	134	__( 'Wallpaper registration requires a non-empty `label`.', 'desktop-mode' ),
124	135	array( 'id' => $id )
125	136	);
126	137	}
		@@ -131,10 +142,10 @@
131	142	// `mount` callback is published on the JS global by that
132	143	// script). CSS wallpapers can skip the script — the shell can
133	144	// render from the `value` / `preview` string alone.
134	145	if ( 'canvas' === $type && '' === (string) $args['script'] ) {
135		- return desktop_mode_registration_error(
136		- 'desktop_mode_missing_script',
	146	+ return openstation_registration_error(
	147	+ 'openstation_missing_script',
137	148	__( 'Canvas wallpaper registration requires a `script` handle that publishes the def.', 'desktop-mode' ),
138	149	array( 'id' => $id )
139	150	);
140	151	}
		@@ -167,21 +178,24 @@
167	178	'script' => (string) $args['script'],
168	179	// Plain text by contract — the shell renders it as text, never
169	180	// as HTML, so strip tags here rather than trusting every caller.
170	181	'description' => sanitize_textarea_field( (string) $args['description'] ),
	182	+ // Anything else stores empty and reads as 'dark', so a typo
	183	+ // lands on the old look rather than on invisible icons.
	184	+ 'tone' => in_array( $args['tone'], array( 'light', 'dark' ), true ) ? (string) $args['tone'] : '',
171	185	);
172		- desktop_mode_desktop_wallpaper_registry( $id, $entry );
	186	+ openstation_desktop_wallpaper_registry( $id, $entry );
173	187
174	188	/**
175	189	* Fires after a desktop wallpaper is successfully registered.
176	190	*
177		- * Does NOT fire when `desktop_mode_register_wallpaper()` returns a
	191	+ * Does NOT fire when `openstation_register_wallpaper()` returns a
178	192	* `WP_Error`.
179	193	*
180	194	* @param string $id The wallpaper id.
181	195	* @param array $entry The stored registry entry.
182	196	*/
183		- do_action( 'desktop_mode_wallpaper_registered', $id, $entry );
	197	+ do_action( 'openstation_wallpaper_registered', $id, $entry );
184	198
185	199	return true;
186	200	}
187	201
		@@ -186,14 +200,14 @@
186	200	}
187	201
188	202	/**
189	203	* Internal module-level registry for wallpapers registered via
190		- * {@see desktop_mode_register_wallpaper()}. Same static-store
	204	+ * {@see openstation_register_wallpaper()}. Same static-store
191	205	* pattern as the widget + native-window registries.
192	206	*
193	207	* @internal
194	208	*/
195		-function desktop_mode_desktop_wallpaper_registry( $id = '', $entry = null ) {
	209	+function openstation_desktop_wallpaper_registry( $id = '', $entry = null ) {
196	210	static $store = array();
197	211
198	212	if ( '' === (string) $id ) {
199	213	return $store;
		@@ -210,22 +224,22 @@
210	224	* callback is announced via the JS global the script sets up.
211	225	*
212	226	* @return array[]
213	227	*/
214		-function desktop_mode_build_desktop_wallpapers_payload() {
215		- $registry = desktop_mode_desktop_wallpaper_registry();
	228	+function openstation_build_desktop_wallpapers_payload() {
	229	+ $registry = openstation_desktop_wallpaper_registry();
216	230	if ( ! is_array( $registry ) || empty( $registry ) ) {
217	231	return array();
218	232	}
219	233	/**
220	234	* Filters the server-declared wallpaper list before it ships to
221		- * the shell. Mirrors the JS-side `desktop-mode.wallpapers` filter
	235	+ * the shell. Mirrors the JS-side `os.wallpapers` filter
222	236	* so plugins can rearrange, hide, or override entries at boot
223	237	* without round-tripping through the JS registry.
224	238	*
225	239	* @param array[] $registry The registered wallpaper entries.
226	240	*/
227		- $registry = apply_filters( 'desktop_mode_wallpapers', $registry );
	241	+ $registry = apply_filters( 'openstation_wallpapers', $registry );
228	242	if ( ! is_array( $registry ) ) {
229	243	return array();
230	244	}
231	245	$out = array();
		@@ -233,22 +247,26 @@
233	247	if ( ! is_array( $entry ) || empty( $entry['id'] ) ) {
234	248	continue;
235	249	}
236	250	$handle = isset( $entry['script'] ) ? (string) $entry['script'] : '';
237		- $payload = desktop_mode_resolve_script_payload( $handle );
238		- $out[] = array(
239		- 'id' => (string) $entry['id'],
240		- 'label' => isset( $entry['label'] ) ? (string) $entry['label'] : '',
241		- 'preview' => isset( $entry['preview'] ) ? (string) $entry['preview'] : '',
242		- 'type' => isset( $entry['type'] ) ? (string) $entry['type'] : 'canvas',
243		- 'value' => isset( $entry['value'] ) ? (string) $entry['value'] : '',
244		- 'description' => isset( $entry['description'] ) ? (string) $entry['description'] : '',
245		- 'scriptUrl' => $payload['url'],
246		- 'scriptHandle' => $handle,
247		- 'scriptBefore' => $payload['before'],
248		- 'scriptAfter' => $payload['after'],
249		- 'scriptL10n' => $payload['l10n'],
	251	+ $payload = openstation_resolve_script_payload( $handle );
	252	+ $out[] = array(
	253	+ 'id' => (string) $entry['id'],
	254	+ 'label' => isset( $entry['label'] ) ? (string) $entry['label'] : '',
	255	+ 'preview' => isset( $entry['preview'] ) ? (string) $entry['preview'] : '',
	256	+ 'type' => isset( $entry['type'] ) ? (string) $entry['type'] : 'canvas',
	257	+ 'value' => isset( $entry['value'] ) ? (string) $entry['value'] : '',
	258	+ 'description' => isset( $entry['description'] ) ? (string) $entry['description'] : '',
	259	+ 'tone' => isset( $entry['tone'] ) ? (string) $entry['tone'] : '',
	260	+ 'scriptUrl' => $payload['url'],
	261	+ 'scriptHandle' => $handle,
	262	+ 'scriptBefore' => $payload['before'],
	263	+ 'scriptAfter' => $payload['after'],
	264	+ 'scriptL10n' => $payload['l10n'],
250	265	'scriptTranslations' => $payload['translations'],
	266	+ // The handle's dependency closure, replayed before the bundle
	267	+ // on its lazy load — see `openstation_resolve_script_dependencies()`.
	268	+ 'scriptDeps' => openstation_resolve_script_dependencies( $handle ),
251	269	);
252	270	}
253	271	return $out;
254	272	}
		@@ -253,25 +271,23 @@
253	271	return $out;
254	272	}
255	273
256	274
257		-/**
258		- * Enqueue plugin-registered wallpaper scripts on the shell page
259		- * so wallpapers active at boot time have their defs available
260		- * without any dynamic-load roundtrip.
	275	+/*
	276	+ * Wallpaper scripts are NOT enqueued here, and that is deliberate.
	277	+ *
	278	+ * A canvas wallpaper's bundle IS the wallpaper — Living Tree is 58 KB
	279	+ * of PixiJS scene, Snow is 42 KB — and this file used to
	280	+ * `wp_enqueue_script()` every registered one on every admin page, so
	281	+ * that every user downloaded and parsed every wallpaper in the
	282	+ * install including the ones they were not wearing. The metadata in
	283	+ * the boot payload (label, preview swatch, description) is enough for
	284	+ * the shell to register a stub and paint a picker tile without any of
	285	+ * it.
	286	+ *
	287	+ * The bundle arrives when something needs the callbacks: the shell
	288	+ * hydrates the user's ACTIVE wallpaper during the boot sync, and the
	289	+ * wallpaper picker hydrates the rest when it opens. See
	290	+ * `src/wallpapers/lazy.ts`. `scriptUrl` in the payload (built above)
	291	+ * is what makes that possible; nothing else on the PHP side is
	292	+ * involved.
261	293	*/
262		-function desktop_mode_enqueue_desktop_wallpaper_scripts() {
263		- if ( ! desktop_mode_is_enabled() || desktop_mode_is_chromeless_request() || desktop_mode_is_classic_request() ) {
264		- return;
265		- }
266		- $registry = desktop_mode_desktop_wallpaper_registry();
267		- if ( ! is_array( $registry ) ) {
268		- return;
269		- }
270		- foreach ( $registry as $entry ) {
271		- if ( ! empty( $entry['script'] ) ) {
272		- wp_enqueue_script( $entry['script'] );
273		- }
274		- }
275		-}
276		-add_action( 'admin_enqueue_scripts', 'desktop_mode_enqueue_desktop_wallpaper_scripts', 20 );
277		-