← All changes | includes/components.php +100 -64 0.9.8 → 1.1.10 View file →

		@@ -1,34 +1,34 @@
1	1	<?php
2	2	/**
3		- * Desktop Mode — PHP helpers for plugin authors.
	3	+ * OpenStation — PHP helpers for plugin authors.
4	4	*
5	5	* Two companion helpers live here:
6	6	*
7		- * - {@see desktop_mode_component()} prints a `<wpd-*>` tag with
	7	+ * - {@see openstation_component()} prints a `<os-*>` tag with
8	8	* safely-escaped attributes (plus its style-array
9	9	* serializers). The intent is explicit (we're rendering a kit
10	10	* component, not arbitrary HTML) and the escape discipline is
11	11	* automatic.
12	12	*
13		- * - {@see desktop_mode_enqueue_script()} wraps
14		- * `wp_enqueue_script()` with the `desktop-mode` + `wp-hooks`
	13	+ * - {@see openstation_enqueue_script()} wraps
	14	+ * `wp_enqueue_script()` with the `openstation` + `wp-hooks`
15	15	* dependencies pre-wired, so shell-extending scripts always
16		- * load after `wp.desktop.*` and `wp.hooks` are available.
	16	+ * load after `wp.os.*` and `wp.hooks` are available.
17	17	*
18		- * {@see desktop_mode_register_window()} moved to
	18	+ * {@see openstation_register_window()} moved to
19	19	* `includes/registries/native-windows.php`.
20	20	*
21		- * @package WPDesktopMode
	21	+ * @package OpenStation
22	22	*/
23	23
24	24	defined( 'ABSPATH' ) || exit;
25	25
26	26	/**
27		- * Output a `<wpd-*>` component with safely escaped attributes.
	27	+ * Output a `<os-*>` component with safely escaped attributes.
28	28	*
29	29	* ```php
30		- * desktop_mode_component( 'wpd-button', array(
	30	+ * openstation_component( 'os-button', array(
31	31	* 'variant' => 'primary',
32	32	* 'data-op' => 'add',
33	33	* 'aria-label' => __( 'Add', 'my-plugin' ),
34	34	* ), '+' );
		@@ -41,9 +41,9 @@
41	41	*
42	42	* Boolean-style attributes (present with a `true` value or an
43	43	* empty string) render as bare attributes (`disabled`,
44	44	* `fill-cell`) — matches the HTML5 boolean-attribute convention
45		- * every `<wpd-*>` follows.
	45	+ * every `<os-*>` follows.
46	46	*
47	47	* ## Inline styles
48	48	*
49	49	* The `style` key accepts either the usual string value or an
		@@ -53,9 +53,9 @@
53	53	* …) so `'padding' => 0` produces `padding: 0` and
54	54	* `'padding' => 16` produces `padding: 16px`.
55	55	*
56	56	* ```php
57		- * desktop_mode_component( 'wpd-stack', array(
	57	+ * openstation_component( 'os-stack', array(
58	58	* 'gap' => 12,
59	59	* 'style' => array(
60	60	* 'padding' => 0,
61	61	* 'background' => 'rgba(0,0,0,0.04)',
		@@ -61,31 +61,31 @@
61	61	* 'background' => 'rgba(0,0,0,0.04)',
62	62	* 'border-radius' => 8,
63	63	* ),
64	64	* ), $children );
65		- * // <wpd-stack gap="12" style="padding: 0; background: rgba(0,0,0,0.04); border-radius: 8px">
	65	+ * // <os-stack gap="12" style="padding: 0; background: rgba(0,0,0,0.04); border-radius: 8px">
66	66	* ```
67	67	*
68	68	* Plain string form (for one-line overrides) keeps working:
69	69	*
70	70	* ```php
71		- * desktop_mode_component( 'wpd-stack', array(
	71	+ * openstation_component( 'os-stack', array(
72	72	* 'style' => 'padding: 0; margin-top: 16px',
73	73	* ), $children );
74	74	* ```
75	75	*
76		- * @param string $tag Tag name, e.g. `wpd-button`.
77		- * Whitelisted to the `wpd-*` prefix
78		- * to prevent the helper being
79		- * misused as a generic HTML emitter.
80		- * @param array<string,mixed> $attrs Attribute key/value pairs.
81		- * `style` may be a string or an
82		- * associative array (see above).
83		- * @param string $content Inner HTML. Pass pre-escaped.
	76	+ * @param string $tag Tag name, e.g. `os-button`.
	77	+ * Whitelisted to the `os-*` prefix
	78	+ * to prevent the helper being
	79	+ * misused as a generic HTML emitter.
	80	+ * @param array<string,mixed> $attrs Attribute key/value pairs.
	81	+ * `style` may be a string or an
	82	+ * associative array (see above).
	83	+ * @param string $content Inner HTML. Pass pre-escaped.
84	84	*/
85		-function desktop_mode_component( $tag, $attrs = array(), $content = '' ) {
	85	+function openstation_component( $tag, $attrs = array(), $content = '' ) {
86	86	$tag = strtolower( (string) $tag );
87		- if ( ! preg_match( '/^wpd-[a-z][a-z0-9-]*$/', $tag ) ) {
	87	+ if ( ! preg_match( '/^os-[a-z][a-z0-9-]*$/', $tag ) ) {
88	88	// Fail loud in debug so a typo surfaces immediately; silently
89	89	// drop the output in production so a plugin with a bad tag
90	90	// doesn't blow up the page.
91	91	if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
		@@ -92,9 +92,9 @@
92	92	_doing_it_wrong(
93	93	__FUNCTION__,
94	94	sprintf(
95	95	/* translators: %s: the attempted tag name. */
96		- esc_html__( 'desktop_mode_component() only accepts tags with the wpd- prefix; got "%s".', 'desktop-mode' ),
	96	+ esc_html__( 'openstation_component() only accepts tags with the os- prefix; got "%s".', 'desktop-mode' ),
97	97	esc_html( $tag )
98	98	),
99	99	'0.5.0'
100	100	);
		@@ -116,9 +116,9 @@
116	116	// Style array — serialize to a CSS declaration list. Plain
117	117	// string values fall through to the generic attribute path
118	118	// below so `'style' => 'padding:0'` keeps working.
119	119	if ( 'style' === strtolower( $key ) && is_array( $value ) ) {
120		- $serialized = desktop_mode_serialize_style_array( $value );
	120	+ $serialized = openstation_serialize_style_array( $value );
121	121	if ( '' === $serialized ) {
122	122	continue;
123	123	}
124	124	$attr_parts[] = sprintf(
		@@ -160,9 +160,9 @@
160	160	$attr_str = $attr_parts ? ' ' . implode( ' ', $attr_parts ) : '';
161	161
162	162	printf(
163	163	'<%1$s%2$s>%3$s</%1$s>',
164		- // `$tag` is validated above against the wpd- allowlist; safe.
	164	+ // `$tag` is validated above against the os- allowlist; safe.
165	165	$tag, // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
166	166	// `$attr_str` is pre-escaped via esc_attr() for each component.
167	167	$attr_str, // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped
168	168	// `$content` is the caller's responsibility to pre-escape.
		@@ -176,29 +176,65 @@
176	176	* interpreting raw numeric values — keeping the same list in
177	177	* one place so PHP `'padding' => 16` and JS `padding: 16` make
178	178	* the same visual decision.
179	179	*/
180		-const DESKTOP_MODE_LENGTH_CSS_PROPERTIES = array(
181		- 'width', 'height',
182		- 'min-width', 'min-height', 'max-width', 'max-height',
183		- 'padding', 'padding-top', 'padding-right', 'padding-bottom', 'padding-left',
184		- 'padding-inline', 'padding-inline-start', 'padding-inline-end',
185		- 'padding-block', 'padding-block-start', 'padding-block-end',
186		- 'margin', 'margin-top', 'margin-right', 'margin-bottom', 'margin-left',
187		- 'margin-inline', 'margin-inline-start', 'margin-inline-end',
188		- 'margin-block', 'margin-block-start', 'margin-block-end',
189		- 'gap', 'row-gap', 'column-gap',
190		- 'border-width', 'border-top-width', 'border-right-width',
191		- 'border-bottom-width', 'border-left-width',
	180	+const OPENSTATION_LENGTH_CSS_PROPERTIES = array(
	181	+ 'width',
	182	+ 'height',
	183	+ 'min-width',
	184	+ 'min-height',
	185	+ 'max-width',
	186	+ 'max-height',
	187	+ 'padding',
	188	+ 'padding-top',
	189	+ 'padding-right',
	190	+ 'padding-bottom',
	191	+ 'padding-left',
	192	+ 'padding-inline',
	193	+ 'padding-inline-start',
	194	+ 'padding-inline-end',
	195	+ 'padding-block',
	196	+ 'padding-block-start',
	197	+ 'padding-block-end',
	198	+ 'margin',
	199	+ 'margin-top',
	200	+ 'margin-right',
	201	+ 'margin-bottom',
	202	+ 'margin-left',
	203	+ 'margin-inline',
	204	+ 'margin-inline-start',
	205	+ 'margin-inline-end',
	206	+ 'margin-block',
	207	+ 'margin-block-start',
	208	+ 'margin-block-end',
	209	+ 'gap',
	210	+ 'row-gap',
	211	+ 'column-gap',
	212	+ 'border-width',
	213	+ 'border-top-width',
	214	+ 'border-right-width',
	215	+ 'border-bottom-width',
	216	+ 'border-left-width',
192	217	'border-radius',
193		- 'border-top-left-radius', 'border-top-right-radius',
194		- 'border-bottom-left-radius', 'border-bottom-right-radius',
195		- 'top', 'right', 'bottom', 'left',
	218	+ 'border-top-left-radius',
	219	+ 'border-top-right-radius',
	220	+ 'border-bottom-left-radius',
	221	+ 'border-bottom-right-radius',
	222	+ 'top',
	223	+ 'right',
	224	+ 'bottom',
	225	+ 'left',
196	226	'inset',
197		- 'inset-inline-start', 'inset-inline-end',
198		- 'inset-block-start', 'inset-block-end',
199		- 'font-size', 'letter-spacing', 'word-spacing', 'text-indent',
200		- 'outline-width', 'outline-offset',
	227	+ 'inset-inline-start',
	228	+ 'inset-inline-end',
	229	+ 'inset-block-start',
	230	+ 'inset-block-end',
	231	+ 'font-size',
	232	+ 'letter-spacing',
	233	+ 'word-spacing',
	234	+ 'text-indent',
	235	+ 'outline-width',
	236	+ 'outline-offset',
201	237	);
202	238
203	239	/**
204	240	* Serialize an associative array of CSS declarations into a
		@@ -214,9 +250,9 @@
214	250	* @param array<string,mixed> $styles
215	251	* @return string CSS declaration list, or empty string when no
216	252	* valid declarations were produced.
217	253	*/
218		-function desktop_mode_serialize_style_array( $styles ) {
	254	+function openstation_serialize_style_array( $styles ) {
219	255	if ( ! is_array( $styles ) ) {
220	256	return '';
221	257	}
222	258	$parts = array();
		@@ -227,9 +263,9 @@
227	263	}
228	264	if ( false === $value || null === $value ) {
229	265	continue;
230	266	}
231		- $serialized = desktop_mode_format_css_value( $prop, $value );
	267	+ $serialized = openstation_format_css_value( $prop, $value );
232	268	if ( '' === $serialized ) {
233	269	continue;
234	270	}
235	271	$parts[] = $prop . ': ' . $serialized;
		@@ -254,9 +290,9 @@
254	290	* @param mixed $value Raw value (int, float, string).
255	291	* @return string CSS value, or empty string when $value is
256	292	* not serializable.
257	293	*/
258		-function desktop_mode_format_css_value( $property, $value ) {
	294	+function openstation_format_css_value( $property, $value ) {
259	295	if ( is_bool( $value ) || null === $value ) {
260	296	return '';
261	297	}
262	298	$text = trim( (string) $value );
		@@ -266,9 +302,9 @@
266	302	if ( preg_match( '/^-?\d+(\.\d+)?$/', $text ) ) {
267	303	if ( '0' === $text ) {
268	304	return '0';
269	305	}
270		- if ( in_array( $property, DESKTOP_MODE_LENGTH_CSS_PROPERTIES, true ) ) {
	306	+ if ( in_array( $property, OPENSTATION_LENGTH_CSS_PROPERTIES, true ) ) {
271	307	return $text . 'px';
272	308	}
273	309	}
274	310	return $text;
		@@ -304,11 +340,11 @@
304	340	*
305	341	* Thin wrapper around `wp_enqueue_script` that pre-wires the correct
306	342	* dependencies so the script:
307	343	*
308		- * - Runs AFTER `desktop-mode` (the shell bundle) so `wp.desktop.*` is
	344	+ * - Runs AFTER `openstation` (the shell bundle) so `wp.os.*` is
309	345	* guaranteed available.
310		- * - Runs AFTER `wp-hooks` so `wp.hooks.addAction( 'desktop-mode.init', ... )`
	346	+ * - Runs AFTER `wp-hooks` so `wp.hooks.addAction( 'os.init', ... )`
311	347	* works without the plugin author having to remember that dep.
312	348	*
313	349	* Intended to be called from `admin_enqueue_scripts` — the wrapper
314	350	* itself does not add an `is_admin()` guard.
		@@ -319,9 +355,9 @@
319	355	* add_action( 'admin_enqueue_scripts', function () {
320	356	* wp_enqueue_script(
321	357	* 'my-plugin',
322	358	* plugins_url( 'my-plugin.js', __FILE__ ),
323		- * array( 'desktop-mode', 'wp-hooks' ),
	359	+ * array( 'openstation', 'wp-hooks' ),
324	360	* '1.0.0',
325	361	* true
326	362	* );
327	363	* } );
		@@ -330,9 +366,9 @@
330	366	* which becomes:
331	367	*
332	368	* ```php
333	369	* add_action( 'admin_enqueue_scripts', function () {
334		- * desktop_mode_enqueue_script(
	370	+ * openstation_enqueue_script(
335	371	* 'my-plugin',
336	372	* plugins_url( 'my-plugin.js', __FILE__ ),
337	373	* array(), // extra deps on top of the desktop defaults
338	374	* '1.0.0'
		@@ -339,23 +375,23 @@
339	375	* );
340	376	* } );
341	377	* ```
342	378	*
343		- * @param string $handle Script handle.
344		- * @param string $src Full URL of the script, or path relative
345		- * to the WordPress root directory.
346		- * @param string[] $extra_deps Additional dependency handles. `desktop-mode`
347		- * and `wp-hooks` are always prepended.
	379	+ * @param string $handle Script handle.
	380	+ * @param string $src Full URL of the script, or path relative
	381	+ * to the WordPress root directory.
	382	+ * @param string[] $extra_deps Additional dependency handles. `openstation`
	383	+ * and `wp-hooks` are always prepended.
348	384	* @param string|bool|null $version Version string, or `false` for none.
349		- * Defaults to `DESKTOP_MODE_VERSION` so plugin authors
	385	+ * Defaults to `OPENSTATION_VERSION` so plugin authors
350	386	* don't have to busy-track cache busting.
351		- * @param bool $in_footer Whether to enqueue in the footer. Defaults
352		- * to `true` — the shell is always in head.
	387	+ * @param bool $in_footer Whether to enqueue in the footer. Defaults
	388	+ * to `true` — the shell is always in head.
353	389	* @return void
354	390	*/
355		-function desktop_mode_enqueue_script( $handle, $src, $extra_deps = array(), $version = null, $in_footer = true ) {
	391	+function openstation_enqueue_script( $handle, $src, $extra_deps = array(), $version = null, $in_footer = true ) {
356	392	$deps = array_merge(
357		- array( 'desktop-mode', 'wp-hooks' ),
	393	+ array( 'openstation', 'wp-hooks' ),
358	394	is_array( $extra_deps ) ? $extra_deps : array()
359	395	);
360	396
361	397	wp_enqueue_script(
		@@ -361,8 +397,8 @@
361	397	wp_enqueue_script(
362	398	$handle,
363	399	$src,
364	400	$deps,
365		- null === $version ? DESKTOP_MODE_VERSION : $version,
	401	+ null === $version ? OPENSTATION_VERSION : $version,
366	402	$in_footer
367	403	);
368	404	}