\NeedsTeXFormat{LaTeX2e}
\ProvidesExplPackage{PrimeTeX/packages/Floats}{2025-09-03}{1.0}{
	Custom Float Environments.
}

\floatstyle{plain}
\newfloat{generic}{htpb}{lgf}
\floatplacement{figure}{htpb}
\floatplacement{table}{htpb}

% Function for converting clists generated by multichoice keys into strings.
\NewDocumentCommand{\clist_use_default:Nnnn}{
	% #1: Output string variable.
	m
	% #2: Input clist.
	m
	% #3: Default clist to use if #2 is empty.
	m
	% #4: Separator for \clist_use:Nn.
	O{}
}{
	\clist_if_empty:NT #2 {
		\clist_set:Ne #2 {#3}
	}
	\str_set:Ne #1 {
		\clist_use:Nn #2 {#4}
	}
}

\clist_const:Nn \c_Float_placement_clist {h,t,p,b}

\clist_new:N \l_Float_placement_clist

% Create a set of keys that are common to all floating environments.
\keys_define:nn {Float} {
	placement	.multichoices:nn	= {b,H,h,p,t}{
		\clist_put_right:Ne \l_Float_placement_clist {\l_keys_choice_tl}
	},
}

% Maximum width adjustment to fit 2 16x9 screensots on one page.
\dim_const:Nn \c_BigFloat_overhang_dim {0.54in}
\str_const:Nn \c_BigFloat_type_str {generic}
\fp_const:Nn \c_BigFloat_offset_fp {2.0}

\ProvideLength{\BigFloatOverhang}[\dim_use:N \c_BigFloat_overhang_dim]
\NewDocumentCommand{\BigFloatOffset}{O{}}{
	\str_if_empty:NTF #1 {
		\fp_use:N \c_BigFloat_offset_fp
	} {
		\fp_set:Ne \c_BigFloat_offset_fp {#1}
	}
}

\dim_new:N \l_BigFloat_workoverhang_dim

\keys_define:nn {} {
	BigFloat	.inherit:n	= {Float},
}

\keys_define:nn{BigFloat}{
	figure		.code:n		= {\str_set:Nn \l_BigFloat_type_str {figure}},

	maxoverhang	.dim_set:N	= \l_BigFloat_maxoverhang_dim,
	maxoverhang	.initial:n	= {1in},

	offset		.fp_set:N	= \l_BigFloat_offset_fp,
	offset		.default:e	= {\c_BigFloat_offset_fp},
	offset		.initial:e	= {\c_BigFloat_offset_fp},

	overhang	.dim_set:N	= \l_BigFloat_overhang_dim,
	overhang	.default:e	= {\c_BigFloat_overhang_dim},
	overhang	.initial:e	= {\c_BigFloat_overhang_dim},

	table		.code:n		= {\str_set:Nn \l_BigFloat_type_str {table}},

	type		.choices:nn	= {figure,generic,table}{
		\str_set:Ne \l_BigFloat_type_str {\l_keys_choice_tl}
	},
	type		.default:e	= {\c_BigFloat_type_str},
	type		.initial:e	= {\c_BigFloat_type_str},
}

\NewDocumentEnvironment{BigFloat}{
	% #1: Key=value options.
	O{}
	% #2: Body: what appears in the BigFloat.
	+b
}{ \group_begin:
	\keys_set:nn{BigFloat}{#1}
	\clist_use_default:Nnnn \l_BigFloat_placement_str
		{\l_Float_placement_clist}
		{\c_Float_placement_clist}
	\dim_set:Nn \l_BigFloat_workoverhang_dim {
		\dim_min:nn {\l_BigFloat_overhang_dim} {\l_BigFloat_maxoverhang_dim}
	}
	\expanded{\noexpand\begin{\l_BigFloat_type_str}[\l_BigFloat_placement_str]}% float environment
		\begin{SmartAdjustWidth}{
			\fp_to_dim:n {
				-\l_BigFloat_workoverhang_dim
			}
		}{
			\fp_to_dim:n {
				-\l_BigFloat_workoverhang_dim
				* \l_BigFloat_offset_fp
			}
		}
			\begin{minipage}{\linewidth}
				\bool_if:NTF \g_draft_bool {
					{\color{layoutColor}\rule{\textwidth}{1pt}\zws}
					#2
				} {
					#2
				}
			\end{minipage}
		\end{SmartAdjustWidth}
	\expanded{\noexpand\end{\l_BigFloat_type_str}}
\group_end: }{}

\clist_const:Nn \c_CenterFig_placement_clist {h, t, p, b}

\keys_define:nn {} {
	CenterFig	.inherit:n	= {Float},
}

\NewDocumentCommand{\CenterFig}{
	% #1: Star argument. If present, graphic is automatically scaled to line
	% width. (Not working, do not use.)
	s
	% #2: Key-value options.
	O{}
	% #3: Graphic file.
	m
	% #4: Key-value options passed to \includegraphics.
	O{}
	% #5: Label.
	>{\TrimSpaces}m
	% #6: Caption.
	m
}{ \group_begin:
	\keys_set:nn{CenterFig}{#2}
	\str_set:Nn \l_CenterFig_passed_keys_str {#4}
	% \bool_if:nT {#1} {
	% 	\str_put_left:Nn \l_CenterFig_passed_keys_str {width=\linewidth,}
	% }
	\clist_use_default:Nnnn \l_CenterFig_placement_str
		{\l_Float_placement_clist}
		{\c_Float_placement_clist}
	\expanded{\noexpand\begin{figure}[\l_CenterFig_placement_str]}
		\begin{MyCaption}{fig:#5}{#6}
			\Centering
			\includegraphics[keepaspectratio,#4]{#3}
		\end{MyCaption}
	\end{figure}
\group_end: }

\keys_define:nn{}{
	BigFig	.inherit:n	= BigFloat,
}

\keys_define:nn{BigFig}{
	hres	.fp_set:N		= \l_BigFig_hres_fp,
	hres	.initial:n		= {0},
	hres	.default:n		= {0},

	dpi		.fp_set:N		= \l_BigFig_dpi_fp,
	dpi		.initial:n		= {96},
	dpi		.default:n		= {96},

	scale	.fp_set:N		= \l_BigFig_scale_fp,
	scale	.initial:n		= {1},
	scale	.default:n		= {1},
}

\dim_new:N \l_BigFig_overhang_dim

\NewDocumentCommand{\BigFig}{
	% Key=value options.
	O{}
	% Graphic file.
	m
	% Label.
	>{\TrimSpaces}m
	% Caption.
	m
}{ \group_begin:
	\keys_set:nn{BigFig}{#1}
	\fp_compare:nNnTF {\l_BigFig_hres_fp} = {0} {
		\dim_set:Nn \l_BigFig_overhang_dim {\l_BigFloat_overhang_dim}
	}{
		\dim_set:Nn \l_BigFig_overhang_dim {
			\dim_eval:n{
				(\fp_to_dim:n{
					  \l_BigFig_scale_fp
					* \l_BigFig_hres_fp
					/ \l_BigFig_dpi_fp
					* 72.27
				}
				- \linewidth)
			/ 3}
		}
	}{}
	\begin{BigFloat}[
		type		= figure,
		overhang	= \l_BigFig_overhang_dim,
		placement:e	= \l_Float_placement_clist,
		offset		= \l_BigFloat_offset_fp,
	]
		\begin{MyCaption}{fig:#3}{#4}
			\includegraphics[keepaspectratio,width=\linewidth]{#2}
		\end{MyCaption}
	\end{BigFloat}
\group_end: }

\keys_define:nn{}{
	DoubleBigFig	.inherit:n	= {BigFloat},
}

\dim_const:Nn \c_DoubleBigFig_space_dim {6pt}

\keys_define:nn {DoubleBigFig} {
	space		.dim_set:N	= \l_DoubleBigFig_space_dim,
	space		.initial:e	= {\c_DoubleBigFig_space_dim},
}

\NewDocumentCommand{\DoubleBigFig}{
	% Key=value options.
	O{}
	% First graphic filename.
	m
	% First graphic label.
	>{\TrimSpaces}m
	% First graphic caption.
	m
	% Second graphic filename.
	m
	% Second graphic label.
	>{\TrimSpaces}m
	% Second Graphic caption.
	m
}{ \group_begin:
	% The following is a hack to keep the figure counter from incrementing by 4
	% instead of 2. Replace it with a proper solution if you find one.
	\addtocounter{figure}{-2}

	\keys_set:nn{DoubleBigFig}{#1}
	\begin{BigFloat}[
		type		= figure,
		overhang	= \l_BigFloat_overhang_dim,
		placement:e	= \l_Float_placement_clist,
		offset		= \l_BigFloat_offset_fp,
	]
		\begin{tblr}{
			colspec	= {Q[c,wd=\linewidth]},
			cells	= {font=\mdseries},
			hlines	= {0pt},
			hborder{1,Z} = {
				abovespace	= 0pt,
				belowspace	= 0pt,
			},
			hborder{2} = {
				abovespace	= \l_DoubleBigFig_space_dim,
				belowspace	= \l_DoubleBigFig_space_dim,
			},
			vborder{1-Z} = {
				leftspace	= 0pt,
				rightspace	= 0pt,
			},
		}
			\begin{MyCaption}{fig:#3}{#4}
				\includegraphics[keepaspectratio,width=\linewidth]{#2}
			\end{MyCaption}
		\\
			\begin{MyCaption}{fig:#6}{#7}
				\includegraphics[keepaspectratio,width=\linewidth]{#5}
			\end{MyCaption}
		\end{tblr}
	\end{BigFloat}
\group_end: }

\dim_const:Nn \c_TwinFig_space_dim {3pt}
\dim_const:Nn \c_TwinFig_width_dim {
	\textwidth / 2 + \c_BigFloat_overhang_dim * 3 / 2 - \c_TwinFig_space_dim
}

\ProvideLength{\TwinFigWidth}[\dim_use:N \c_TwinFig_width_dim]

\fp_new:N \l_TwinFig_valign_offset_fp

\keys_define:nn {} {
	TwinFig		.inherit:n	= {BigFloat},
}

\keys_define:nn{TwinFig}{
	valign		.choices:nn	= {b,f,h,m,t}{
		\str_set:Ne \l_TwinFig_valign_str {\l_keys_choice_tl}
	},
	valign		.initial:n	= {m},

	width		.dim_set:N	= \l_TwinFig_width_dim,
	width		.initial:e	= {\c_TwinFig_width_dim},

	space		.dim_set:N	= \l_TwinFig_space_dim,
	space		.initial:e	= {\c_TwinFig_space_dim},
}

\NewDocumentCommand{\TwinFig}{
	% #1: Key=value options.
	O{}
	% #2: First graphic file.
	m
	% #3: First label.
	>{\TrimSpaces}m
	% #4: First caption.
	>{\TrimSpaces}m
	% #5: Second graphic file.
	m
	% #6: Second label.
	>{\TrimSpaces}m
	% #7: Second caption.
	>{\TrimSpaces}m
}{ \group_begin:
	% The following is a hack to keep the figure counter from incrementing by 4
	% instead of 2. Replace it with a proper solution if you find one.
	\addtocounter{figure}{-2}
	\keys_set:nn{TwinFig}{#1}
	\begin{BigFloat}[
		type		= {figure},
		overhang	= \l_BigFloat_overhang_dim,
		placement:e	= \l_Float_placement_clist,
		offset		= \l_BigFloat_offset_fp,
	]
		\begin{tblr}{
			colspec	= {*{2}{Q[c,wd=\l_TwinFig_width_dim,]}},
			cells	= {font=\mdseries},
			rows:e	= {\l_TwinFig_valign_str},
			hlines	= {0pt},
			hborder{1-Z} = {
				abovespace	= 0pt,
				belowspace	= 0pt,
			},
			vborder{1,Z} = {
				leftspace	= 0pt,
				rightspace	= 0pt,
			},
			vborder{2} = {
				leftspace	= \l_TwinFig_space_dim,
				rightspace	= \l_TwinFig_space_dim,
			},
		}
			\begin{MyCaption}{fig:#3}{#4}
				\includegraphics[
					keepaspectratio,
					align	= c,
					width	= \l_TwinFig_width_dim,
				]{#2}
			\end{MyCaption}
			&
			\begin{MyCaption}{fig:#6}{#7}
				\includegraphics[
					keepaspectratio,
					align	= c,
					width	= \l_TwinFig_width_dim,
				]{#5}
			\end{MyCaption}
			\\
		\end{tblr}
	\end{BigFloat}
\group_end: }