PrimeTeX/packages/Floats.sty

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

\RequirePackage{PrimeTeX/packages/Layout}

% I think this redefines how float environments evaluate the placement argument,
% allowing a command in the argument to be expanded before it is used. Otherwise
% it thinks we are trying to use the literal command name as the placement.
\def\ExpEnvOption#1#2[#3]{%
	\expandafter\@expenvopt\expandafter{#3}{#1}{#2}
}
\def\@expenvopt#1#2#3{#2{#3}[#1]}

\RequirePackage{float}

\floatstyle{plain}
\newfloat{generic}{htpb}{lgf}

% 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}
	}
}

% 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}
\clist_const:Nn \c_BigFloat_placement_clist {h,t,p,b}
\fp_const:Nn \c_BigFloat_offset_fp {2.0}

\ProvideLength{\BigFloatOverhang}[\dim_use:N \c_BigFloat_overhang_dim]
\NewDocumentCommand{\BigFloatOffset}{}{\fp_use:N \c_BigFloat_offset_fp}

\clist_new:N \l_BigFloat_placement_clist

\keys_define:nn{BigFloat}{
	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},

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

	placement	.multichoices:nn	= {b,H,h,p,t}{
		\clist_put_right:Ne \l_BigFloat_placement_clist {\l_keys_choice_tl}
	},

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

\NewDocumentEnvironment{BigFloat}{
	% #1: Key=value options.
	O{}
	% #2: Body: what appears in the BigFloat.
	+b
}{%
	\keys_set:nn{BigFloat}{#1}%
	\clist_use_default:Nnnn \l_BigFloat_placement_str
		{\l_BigFloat_placement_clist}
		{\c_BigFloat_placement_clist}
	\ExpEnvOption%
	\begin{\l_BigFloat_type_str}[\l_BigFloat_placement_str]% float environment
		\begin{SmartAdjustWidth}{%

			\fp_to_dim:n {
				-\l_BigFloat_overhang_dim
			}%
		}{%
			\fp_to_dim:n {%
				-\l_BigFloat_overhang_dim
				* \l_BigFloat_offset_fp
			}%
		}%
			\begin{minipage}{\linewidth}%
				\ifthenelse{\boolean{isDraft}}{%
					{\color{layout}\rule{\textwidth}{1pt}\zws}%
					#2%
				}{%
					#2%
				}%
			\end{minipage}%
		\end{SmartAdjustWidth}%
	\end{\l_BigFloat_type_str}%
}{}

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

\clist_new:N \l_CenterFig_placement_clist

\keys_define:nn{CenterFig}{
	placement	.multichoices:nn= {b,H,h,p,t}{
		\clist_put_right:Nn \l_CenterFig_placement_clist {\l_keys_choice_tl}
	},
}

\NewDocumentCommand{\CenterFig}{
	% Key-value options passed to \includegraphics.
	O{}
	% Key-value options.
	O{}
	% Graphic file.
	m
	% Label.
	>{\TrimSpaces}m
	% Caption.
	m
}{
	\keys_set:nn{CenterFig}{#2}%
	\clist_use_default:Nnnn \l_CenterFig_placement_str
		{\l_CenterFig_placement_clist}
		{\c_CenterFig_placement_clist}
	\ExpEnvOption
	\begin{figure}[\l_CenterFig_placement_str]%
		\Centering%
		\includegraphics[keepaspectratio,#1]{#3}%
		\caption{#5}%
		\label{fig:#4}%
	\end{figure}%
}

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

\NewDocumentCommand{\BigFig}{
	% Key=value options.
	O{}
	% Graphic file.
	m
	% Label.
	>{\TrimSpaces}m
	% Caption.
	m
}{%
	\keys_set:nn{BigFig}{#1}
	\begin{BigFloat}[
		type		= figure,
		overhang	= \l_BigFloat_overhang_dim,
		placement:e	= {\clist_use:Nn \l_BigFloat_placement_clist {}},
		offset		= \l_BigFloat_offset_fp,
	]%
		\captionsetup{type=figure}%
		\includegraphics[keepaspectratio,width=\linewidth]{#2}%
		\Centering\captionof{figure}{#4}%\par
		\label{fig:#3}%
	\end{BigFloat}%
}

\keys_define:nn{DoubleBigFig}{
	overhang	.dim_set:N	= \l_DoubleBigFig_overhang_dim,
	overhang	.initial:e	= {\c_BigFloat_overhang_dim},
%	overhang	.default:e	= {\c_BigFloat_overhang_dim},

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

\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
}{%
	\keys_set:nn{DoubleBigFig}{#1}
	\begin{BigFloat}[
		type		= figure,
		overhang	= \l_DoubleBigFig_overhang_dim,
		placement	= {p},
		offset		= \l_DoubleBigFig_offset_fp,
	]%
		\captionsetup{type=figure}%
		\includegraphics[keepaspectratio,width=\textwidth]{#2}%
		\Centering\captionof{figure}{#4}%
		\label{fig:#3}
		\bigskip
		\captionsetup{type=figure}%
		\includegraphics[keepaspectratio,width=\textwidth]{#5}%
		\Centering\captionof{figure}{#7}%
		\label{fig:#6}%
	\end{BigFloat}%
}

\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]

\keys_define:nn{TwinFig}{
	overhang	.dim_set:N	= \l_TwinFig_overhang_dim,
	overhang	.initial:e	= {\c_BigFloat_overhang_dim},
%	overhang	.default:e	= {\c_BigFloat_overhang_dim},

	placement	.clist_set:N= \l_TwinFig_placement_clist,
	placement	.initial:e	= {\c_BigFloat_placement_clist},
%	placement	.default:e	= {\c_BigFloat_placement_clist},

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

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

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

	space		.dim_set:N	= \l_TwinFig_space_dim,
	space		.initial:e	= {\c_TwinFig_space_dim},
%	space		.default: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
}{%
	\keys_set:nn{TwinFig}{#1}%
	\begin{BigFloat}[
		type		= {figure},
		overhang	= \l_TwinFig_overhang_dim,
		placement:e	= \l_TwinFig_placement_clist,
		offset		= \l_TwinFig_offset_fp,
	]%
		%\typeout{TwinFig~valign:~"\l_TwinFig_valign_str"}
		\begin{tblr}{%
			colspec	= {*{2}{Q[c,wd=\l_TwinFig_width_dim]}},%
			rows:e	= {\l_TwinFig_valign_str},
			hlines	= {0pt},
			%vlines,% For debugging. Comment out when done.
			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,%
			},%
		}%
			\vfill
			\captionsetup{type=figure}%
			\includegraphics[%
				keepaspectratio,width=\l_TwinFig_width_dim%
			]{#2}%
			\captionof{figure}{#4}%
			\label{fig:#3}
			\vfill%
			&%
				\vfill
				\captionsetup{type=figure}%
				\includegraphics[%
					keepaspectratio,width=\l_TwinFig_width_dim%
				]{#5}%
				\captionof{figure}{#7}%
				\label{fig:#6}
				\vfill%
			\\%
		\end{tblr}%
	\end{BigFloat}%
}