yaymail / src / Utils / OrderProgressVariantHelpers.php

OrderProgressVariantHelpers.php in YayMail – WooCommerce Email Customizer trunk, at src/Utils/OrderProgressVariantHelpers.php

263 lines 9.3 KB

Raw Download Zip

1	<?php
2	/**
3	* Pure helpers for Order Progress email templates (mirrors order-progress-variant-logic.ts).
4	*
5	* @package YayMail
6	*/
7
8	namespace YayMail\Utils;
9
10	/**
11	* Order Progress variant helpers.
12	*/
13	class OrderProgressVariantHelpers {
14
15	/**
16	* Step-marker column presets (widths sum 100). Must stay in sync with order-progress-variant-logic.ts (STEP_MARKER_PRESETS).
17	*
18	* @return array Presets keyed by step count 1–5; each has 'widths' and 'aligns' lists.
19	*/
20	public static function get_step_marker_presets() {
21	return [
22	1 => [
23	'widths' => [ 100 ],
24	'aligns' => [ 'center' ],
25	],
26	2 => [
27	'widths' => [ 50, 50 ],
28	'aligns' => [ 'left', 'right' ],
29	],
30	3 => [
31	'widths' => [ 33, 34, 33 ],
32	'aligns' => [ 'left', 'center', 'right' ],
33	],
34	4 => [
35	'widths' => [ 12, 25, 25, 12 ],
36	'aligns' => [ 'left', 'center', 'center', 'right' ],
37	],
38	5 => [
39	'widths' => [ 9, 20, 20, 20, 9 ],
40	'aligns' => [ 'left', 'center', 'center', 'center', 'right' ],
41	],
42	];
43	}
44
45	/**
46	* Connector segment colors for filled-bar inner table (left bar, icon, right bar).
47	*
48	* @param int $index Step index (0-based).
49	* @param int $active_index Active step index (0-based).
50	* @param int $step_count Total steps.
51	* @param string $active_color Connector active color.
52	* @param string $inactive_color Connector inactive color.
53	* @return array{left: string, right: string}
54	*/
55	public static function get_connector_segment_colors( $index, $active_index, $step_count, $active_color, $inactive_color ) {
56	$index = (int) $index;
57	$active_index = (int) $active_index;
58	$step_count = (int) $step_count;
59
60	$left = ( 0 === $index )
61	? 'transparent'
62	: ( $index <= $active_index ? $active_color : $inactive_color );
63
64	$right = ( $index === $step_count - 1 )
65	? 'transparent'
66	: ( $index < $active_index ? $active_color : $inactive_color );
67
68	return [
69	'left' => $left,
70	'right' => $right,
71	];
72	}
73
74	/**
75	* Read step image URL from step array (new key with legacy fallback).
76	*
77	* @param array<string, mixed> $step Step data.
78	* @return string
79	*/
80	public static function get_step_image_url( $step ) {
81	if ( ! is_array( $step ) ) {
82	return '';
83	}
84	$image_url = isset( $step['image_url'] ) ? trim( (string) $step['image_url'] ) : '';
85	if ( '' !== $image_url ) {
86	return $image_url;
87	}
88	$active = isset( $step['image_active_url'] ) ? trim( (string) $step['image_active_url'] ) : '';
89	if ( '' !== $active ) {
90	return $active;
91	}
92	return isset( $step['image_inactive_url'] ) ? trim( (string) $step['image_inactive_url'] ) : '';
93	}
94
95	/**
96	* Element-level active/inactive label color (per-step legacy overrides on read).
97	*
98	* @param array<string, mixed> $step Step data.
99	* @param bool $is_step_active Whether the step is active or completed.
100	* @param string $label_active_color Element label color (active).
101	* @param string $label_inactive_color Element label color (inactive).
102	* @return string
103	*/
104	public static function get_step_label_color(
105	$step,
106	$is_step_active,
107	$label_active_color = '#111827',
108	$label_inactive_color = '#9CA3AF'
109	) {
110	if ( is_array( $step ) ) {
111	$label_color = isset( $step['label_color'] ) ? trim( (string) $step['label_color'] ) : '';
112	if ( '' !== $label_color ) {
113	return $label_color;
114	}
115	if ( $is_step_active ) {
116	$legacy_active = isset( $step['label_active_color'] ) ? trim( (string) $step['label_active_color'] ) : '';
117	if ( '' !== $legacy_active ) {
118	return $legacy_active;
119	}
120	} else {
121	$legacy_inactive = isset( $step['label_inactive_color'] ) ? trim( (string) $step['label_inactive_color'] ) : '';
122	if ( '' !== $legacy_inactive ) {
123	return $legacy_inactive;
124	}
125	}
126	}
127
128	$active_color = trim( (string) $label_active_color );
129	$inactive_color = trim( (string) $label_inactive_color );
130
131	if ( $is_step_active ) {
132	return '' !== $active_color ? $active_color : '#111827';
133	}
134
135	return '' !== $inactive_color ? $inactive_color : '#9CA3AF';
136	}
137
138	/**
139	* Filled-bar icon border from step (new keys with legacy fallback).
140	*
141	* @param array<string, mixed> $step Step data.
142	* @return array{color: string, style: string, width_px: int}
143	*/
144	public static function get_step_icon_border( $step ) {
145	$fallback_color = '#c9a8ff';
146	if ( ! is_array( $step ) ) {
147	return [
148	'color' => $fallback_color,
149	'style' => 'solid',
150	'width_px' => 2,
151	];
152	}
153	$color = isset( $step['icon_border_color'] ) ? trim( (string) $step['icon_border_color'] ) : '';
154	if ( '' === $color && isset( $step['filled_bar_icon_border_color_active'] ) ) {
155	$color = trim( (string) $step['filled_bar_icon_border_color_active'] );
156	}
157	if ( '' === $color && isset( $step['filled_bar_icon_border_color_inactive'] ) ) {
158	$color = trim( (string) $step['filled_bar_icon_border_color_inactive'] );
159	}
160	if ( '' === $color ) {
161	$color = $fallback_color;
162	}
163	$style = isset( $step['icon_border_style'] ) ? strtolower( trim( (string) $step['icon_border_style'] ) ) : 'solid';
164	if ( ! in_array( $style, [ 'solid', 'dashed', 'dotted' ], true ) ) {
165	$style = 'solid';
166	}
167	$width_px = 2;
168	if ( isset( $step['icon_border_width'] ) ) {
169	$width_px = max( 0, min( 10, (int) round( (float) $step['icon_border_width'] ) ) );
170	}
171	return [
172	'color' => $color,
173	'style' => $style,
174	'width_px' => $width_px,
175	];
176	}
177
178	/**
179	* @deprecated Use get_step_image_url() on step array.
180	*/
181	public static function resolve_step_image_url( $is_step_active, $active_url, $inactive_url ) {
182	$active_url = (string) $active_url;
183	$inactive_url = (string) $inactive_url;
184	$chosen = $is_step_active ? $active_url : $inactive_url;
185	if ( '' !== $chosen ) {
186	return $chosen;
187	}
188	return '' !== $active_url ? $active_url : $inactive_url;
189	}
190
191	/**
192	* Filled-bar label text color (per-step label_color with legacy fallbacks).
193	*
194	* @param array<string, mixed> $step Step data.
195	* @param string $legacy_label_color Legacy single label color on step.
196	* @param string $global_label_active_color Element default (legacy).
197	* @param string $global_label_inactive_color Element default (legacy).
198	* @return string
199	*/
200	public static function resolve_filled_bar_label_color(
201	$step,
202	$is_step_active,
203	$label_active_color = '#111827',
204	$label_inactive_color = '#9CA3AF'
205	) {
206	return self::get_step_label_color(
207	$step,
208	$is_step_active,
209	$label_active_color,
210	$label_inactive_color
211	);
212	}
213
214	/**
215	* Filled-bar icon wrapper border color (single per-step color).
216	*
217	* @param array<string, mixed> $step Step data.
218	* @return string
219	*/
220	public static function resolve_filled_bar_icon_border_color( $step ) {
221	$border = self::get_step_icon_border( $step );
222	return $border['color'];
223	}
224
225	/**
226	* Step-marker current-step accent: per-step image_bg_color when set, else connector active.
227	*
228	* @param array<string, mixed> $step Step data.
229	* @param string $connector_active_color Element connector active color.
230	* @return string
231	*/
232	public static function resolve_step_marker_accent_color( $step, $connector_active_color ) {
233	if ( is_array( $step ) ) {
234	$bg = trim( (string) ( $step['image_bg_color'] ?? '' ) );
235	if ( '' !== $bg ) {
236	return $bg;
237	}
238	}
239	return (string) $connector_active_color;
240	}
241
242	/**
243	* Blend a hex color toward white (step-marker ring border).
244	*
245	* @param string $hex Color such as #2563eb.
246	* @param float $amount Blend amount 0–1.
247	* @return string
248	*/
249	public static function blend_hex_with_white( $hex, $amount = 0.55 ) {
250	$raw = ltrim( (string) $hex, '#' );
251	if ( 6 !== strlen( $raw ) \|\| ! ctype_xdigit( $raw ) ) {
252	return '#C4B0E8';
253	}
254	$r0 = hexdec( substr( $raw, 0, 2 ) );
255	$g0 = hexdec( substr( $raw, 2, 2 ) );
256	$b0 = hexdec( substr( $raw, 4, 2 ) );
257	$mix = static function ( $c ) use ( $amount ) {
258	return (int) round( $c + ( 255 - $c ) * $amount );
259	};
260	return sprintf( '#%02x%02x%02x', $mix( $r0 ), $mix( $g0 ), $mix( $b0 ) );
261	}
262	}
263