PrimeTeX/packages/Boxout.sty

\NeedsTeXFormat{LaTeX2e}
\ProvidesExplPackage{PrimeTeX/packages/Boxout}{2025-09-03}{1.0}{
	Commands for typesetting boxouts.
}

\RequirePackage{PrimeTeX/packages/Layout}
\RequirePackage{PrimeTeX/packages/Color}
\RequirePackage{PrimeTeX/packages/Tables}
\RequirePackage{calc}

\ProvideLength{\boxoutpadding}[1em]
\ProvideLength{\boxoutrule}[1pt]

\NewTblrEnviron{tblrBoxout}
\SetTblrInner[tblrBoxout]{
	cells		= {boxoutBG},
	hborder{1}	= {belowspace=\boxoutpadding},
	hborder{Z}	= {abovespace=\boxoutpadding},
	hlines		= {0pt,boxoutBG},
	hline{1,Z}	= {\boxoutrule,boxoutFG},
	vborder{1}	= {rightspace=\boxoutpadding},
	vborder{Z}	= {leftspace=\boxoutpadding},
	vlines		= {0pt,boxoutBG},
	vline{1,Z}	= {\boxoutrule,boxoutFG},
}
% \SetTblrOuter[tblrBoxout]{
% 	expand+		= \l_Boxout_body_tl,
% }

\tl_const:Nn \c_Boxout_innerspec_tl {colspec={X[l,h]}}
\bool_const:Nn \c_Boxout_warning_bool {\c_false_bool}

\tl_new:N \l_Boxout_title_tl

\keys_define:nn{Boxout}{
	innerspec	.tl_set_e:N= \l_Boxout_innerspec_tl,
	innerspec	.initial:e	= {\c_Boxout_innerspec_tl},
	innerspec	.default:e	= {\c_Boxout_innerspec_tl},

	warning		.bool_set:N	= \l_Boxout_warning_bool,
	warning		.initial:e	= {false},
	warning		.default:e	= {true},
}

% \NewExpandableDocumentCommand{\__Boxout_body:Nnn}{m +m +m}{
% 	%\message{boxout~body~start}

% }

\NewDocumentEnvironment{Boxout}{
	% #1: Key-value options.
	O{}
	% #2: Label, passed to @boxout argument #1.
	>{\TrimSpaces}m
	% #3: Caption.
	O{}
	% #4: Body, passed to @boxout.
	+b
}{ \group_begin:
	\keys_set:nn{Boxout}{#1}
	\bool_if:nT \l_Boxout_warning_bool {
		\colorlet{boxoutBG}{warningBG}
		\colorlet{boxoutFG}{warningFG}
	}
	\label{box:#2}
	\tl_if_empty:nTF {#3} {
		\expanded{\noexpand\begin{tblrBoxout}{\l_Boxout_innerspec_tl}}
			\setlength{\parskip}{\medskipamount}
			#4\\
		\end{tblrBoxout}
	}{
		\expanded{\noexpand\begin{tblrBoxout}{\l_Boxout_innerspec_tl}}
			\SetCell{halign=c, font={\sbfamily\bfseries}}{#3}\\
			\setlength{\parskip}{\medskipamount}
			#4\\
		\end{tblrBoxout}
	}
\group_end: }{}

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

\NewDocumentEnvironment{BigBoxout}{
	% #1: Key-value options.
	O{}
	% #2: Label, passed to Boxout argument #1.
	>{\TrimSpaces}m
	% #3: Caption, passed to Boxout argument #3.
	O{}
	% #4: Body, passed to Boxout.
	+b
}{ \group_begin:
	\keys_set:nn{BigBoxout}{#1}
	\begin{BigFloat}[
		type		= generic,
		overhang	= \l_BigFloat_overhang_dim,
		placement:e	= \l_Float_placement_clist,
		offset		= \l_BigFloat_offset_fp,
	]
		\begin{Boxout}[
			innerspec:e	= \l_Boxout_innerspec_tl,
			warning:e	= \bool_to_str:N \l_Boxout_warning_bool,
		]{#2}[#3]
			#4
		\end{Boxout}
	\end{BigFloat}
\group_end: }{}

\str_const:Nn \c_MarginBoxout_position_str {auto}
\dim_const:Nn \c_MarginBoxout_width_dim {\marginparwidth}

\keys_define:nn{}{
	MarginBoxout	.inherit:n	= Boxout,
}

\keys_define:nn{MarginBoxout}{
	position	.choices:nn	= {auto,reverse,left,right,nearest}{
		\str_set:Ne \l_MarginBoxout_position_str {\l_keys_choice_tl}
	},
	position	.initial:e	= {\c_MarginBoxout_position_str},

	width		.dim_set:N	= \l_MarginBoxout_width_dim,
	width		.initial:e	= {\c_MarginBoxout_width_dim},
}

\NewDocumentEnvironment{MarginBoxout}{
	% #1: Key-value options.
	O{}
	% #2: Label.
	>{\TrimSpaces}m
	% #3: Caption
	O{}
	% #4: Body.
	+b
}{ \group_begin:
	\keys_set:nn {MarginBoxout} {#1}
	\marginalia[
		width	= \l_MarginBoxout_width_dim,
	]{
		\begin{Boxout}[
			innerspec:e	= \l_Boxout_innerspec_tl,
			warning:e	= \bool_to_str:N \l_Boxout_warning_bool,
		]{#2}[#3]
			#4
		\end{Boxout}
	}
\group_end: }{}

\tl_const:Nn \c_WrapBoxout_position_tl {o}
\tl_const:Ne \c_WrapBoxout_offset_tl {\marparwidth}
\tl_const:Nn \c_WrapBoxout_width_tl {3in}

\keys_define:nn{}{
	WrapBoxout	.inherit:n	= Boxout,
}
\keys_define:nn{WrapBoxout}{
	position	.choices:nn	= {l,r,c,i,o}{
		\tl_set:Nn \l_WrapBoxout_position_tl {\l_keys_choice_tl}
	},
	position	.initial:e	= {\c_WrapBoxout_position_tl},
	position	.default:e	= {\c_WrapBoxout_position_tl},

	offset		.tl_set:N	= \l_WrapBoxout_offset_tl,
	offset		.initial:e	= {\c_WrapBoxout_offset_tl},
	offset		.default:e	= {\c_WrapBoxout_offset_tl},

	width		.tl_set:N	= \l_WrapBoxout_width_tl,
	width		.initial:e	= {\c_WrapBoxout_width_tl},
	width		.default:e	= {\c_WrapBoxout_width_tl},
}

\NewDocumentEnvironment{WrapBoxout}{
	% #1: Key-value options.
	O{}
	% #2: Label.
	>{\TrimSpaces}m
	% #3: Caption
	O{}
	% #4: Body.
	+b
}{ \group_begin:
	%\keys_set:nn{WrapBoxout}{position,offset,width}
	\keys_set:nn{WrapBoxout}{#1}
	\expanded{\noexpand\begin{wrapstuff}[
		\l_WrapBoxout_position_tl,
		hoffset	= \l_WrapBoxout_offset_tl,
	]}%{\l_WrapBoxout_position_tl}[\l_WrapBoxout_offset_tl]}
		\expanded{\noexpand\begin{minipage}{\l_WrapBoxout_width_tl}}
			\begin{Boxout}[
				innerspec:e	= \l_Boxout_innerspec_tl,
				warning:e	= \bool_to_str:N \l_Boxout_warning_bool,
			]{#2}[#3]
				#4
			\end{Boxout}
		\end{minipage}
	\end{wrapstuff}
\group_end: }{}