% !TEX root = ../HSRTReport.cls
% ==============================================================================
% Page Break Control Configuration Module
% ==============================================================================
% Description: Advanced page break control for sections, paragraphs, listings,
%              and itemize environments to ensure proper page layout
% Author: Frederik Beimgraben
% License: Creative Commons CC BY 4.0
% ==============================================================================

% ==============================================================================
% Required Packages
% ==============================================================================
\RequirePackage{needspace}  % For conditional page breaks based on available space
\RequirePackage{afterpage}  % For deferred page break commands
\RequirePackage{placeins}   % For section barriers to control float placement

% ==============================================================================
% Global Page Break Penalties
% ==============================================================================
% Fine-tune the global penalties for page breaking
\binoppenalty=10000      % Penalty for breaking at binary operators
\relpenalty=10000        % Penalty for breaking at relational operators
\brokenpenalty=10000     % Additional penalty for hyphenated line breaks

% ==============================================================================
% Section-Level Page Break Control
% ==============================================================================
% Define minimum content requirements after sections
\newlength{\sectionminspace}
\newlength{\subsectionminspace}
\newlength{\subsubsectionminspace}

% Set minimum space requirements (approximately 2 paragraphs)
\setlength{\sectionminspace}{12\baselineskip}
\setlength{\subsectionminspace}{10\baselineskip}
\setlength{\subsubsectionminspace}{8\baselineskip}

% Hook into section commands to check space
\pretocmd{\section}{%
	\needspace{\sectionminspace}%
	\FloatBarrier%  % Ensure all floats are placed before new section
}{}{}

\pretocmd{\subsection}{%
	\needspace{\subsectionminspace}%
}{}{}

\pretocmd{\subsubsection}{%
	\needspace{\subsubsectionminspace}%
}{}{}

% ==============================================================================
% Paragraph Cohesion Control
% ==============================================================================
% Keep paragraphs together when possible
\newcommand{\keeptogether}[1]{%
	\begin{minipage}{\linewidth}%
		#1%
	\end{minipage}%
}

% Automatic paragraph protection for short paragraphs
\newcommand{\protectparagraph}{%
	\nopagebreak[4]%
	\interlinepenalty=10000%
}

% ==============================================================================
% Listing Environment Protection
% ==============================================================================
% Redefine lstlisting to prevent page breaks
\let\originallstlisting\lstlisting
\let\endoriginallstlisting\endlstlisting

\renewenvironment{lstlisting}[1][]{%
	\needspace{5\baselineskip}% Ensure minimum space
	\nopagebreak[4]%
	\originallstlisting[#1]%
}{%
	\endoriginallstlisting%
	\nopagebreak[3]%
}

% For inline listings that must stay together
\newenvironment{nobreaklistings}{%
	\begin{minipage}{\linewidth}%
		\vspace{0.5em}%
		}{%
		\vspace{0.5em}%
	\end{minipage}%
}

% ==============================================================================
% Itemize and Enumerate Protection
% ==============================================================================
% Protected itemize that stays with preceding paragraph
\newenvironment{nobreakitemize}{%
	\nopagebreak[4]%
	\begin{minipage}{\linewidth}%
		\begin{itemize}%
			\interlinepenalty=10000%
			}{%
		\end{itemize}%
	\end{minipage}%
	\nopagebreak[3]%
}

% Protected enumerate that stays with preceding paragraph
\newenvironment{nobreakenumerate}{%
	\nopagebreak[4]%
	\begin{minipage}{\linewidth}%
		\begin{enumerate}%
			\interlinepenalty=10000%
			}{%
		\end{enumerate}%
	\end{minipage}%
	\nopagebreak[3]%
}

% Itemize and enumerate hooks are defined in Typography.tex
% to avoid conflicts with the listenabsatz environment

% ==============================================================================
% Description List Protection
% ==============================================================================
\AtBeginEnvironment{description}{%
	\nopagebreak[4]%
	\interlinepenalty=5000%
}
\AtEndEnvironment{description}{%
	\nopagebreak[3]%
}

% ==============================================================================
% Smart Section Breaking
% ==============================================================================
% Command to check if section should be moved to next page
\newcommand{\smartsection}[2][]{%
	\vfil\penalty-9999\vfilneg% Allow break here if needed
	\needspace{\sectionminspace}%
	\section[#1]{#2}%
}

\newcommand{\smartsubsection}[2][]{%
	\vfil\penalty-9999\vfilneg%
	\needspace{\subsectionminspace}%
	\subsection[#1]{#2}%
}

% ==============================================================================
% Figure and Table Protection
% ==============================================================================
% Keep figures with their captions
% Note: Using samepage in figure/table can cause issues with color groups
% Instead, use penalties to discourage breaks
\AtBeginEnvironment{figure}{%
	\nopagebreak[4]%
}
\AtEndEnvironment{figure}{%
	\nopagebreak[3]%
}

% Keep tables with their captions
\AtBeginEnvironment{table}{%
	\nopagebreak[4]%
}
\AtEndEnvironment{table}{%
	\nopagebreak[3]%
}

% ==============================================================================
% Code Block Protection
% ==============================================================================
% For verbatim environments
\AtBeginEnvironment{verbatim}{%
	\nopagebreak[4]%
	\interlinepenalty=10000%
}
\AtEndEnvironment{verbatim}{%
	\nopagebreak[3]%
}

% ==============================================================================
% Math Environment Protection
% ==============================================================================
% Keep equations together
\AtBeginEnvironment{equation}{%
	\nopagebreak[4]%
}
\AtEndEnvironment{equation}{%
	\nopagebreak[3]%
}

\AtBeginEnvironment{align}{%
	\nopagebreak[4]%
	\interlinepenalty=10000%
}
\AtEndEnvironment{align}{%
	\nopagebreak[3]%
}

% ==============================================================================
% Custom Commands for Manual Control
% ==============================================================================
% Force content to stay together
\newcommand{\keeptogetherflex}[1]{%
	\vbox{#1}%
}

% Conditional page break based on remaining space
\newcommand{\conditionalpagebreak}[1][10\baselineskip]{%
	\needspace{#1}%
}

% Mark critical content that should not be split
\newenvironment{critical}{%
	\begin{samepage}%
		\interlinepenalty=10000%
		\widowpenalty=10000%
		\clubpenalty=10000%
		}{%
	\end{samepage}%
}

% ==============================================================================
% Debugging Commands (can be commented out in production)
% ==============================================================================
% Show page break penalties in log
\newcommand{\showpenalties}{%
	\typeout{Current penalties:}%
	\typeout{  Widow: \the\widowpenalty}%
	\typeout{  Club: \the\clubpenalty}%
	\typeout{  Interline: \the\interlinepenalty}%
	\typeout{  Broken: \the\brokenpenalty}%
}

% ==============================================================================
% Table of Contents Page Break Control
% ==============================================================================
% Keep chapters with their sections together in TOC
\newcommand{\protectchapterintoc}{%
	\addtocontents{toc}{\protect\needspace{10\baselineskip}}%
	\addtocontents{toc}{\protect\nopagebreak[4]}%
}

% Add space and break control for TOC chapters
\pretocmd{\chapter}{%
	\protectchapterintoc%
}{}{}

% Configure TOC to keep related entries together
\AtBeginDocument{%
	\addtocontents{toc}{\protect\interlinepenalty=500}%
	\addtocontents{toc}{\protect\widowpenalty=10000}%
	\addtocontents{toc}{\protect\clubpenalty=10000}%
}

% Command to mark TOC entries that should stay together
\newcommand{\tockeeptogether}[1]{%
	\addtocontents{toc}{\protect\begin{minipage}{\textwidth}}%
			#1%
			\addtocontents{toc}{\protect\end{minipage}}%
}

% Automatic TOC chapter grouping for short chapters
\newcounter{tocsectioncount}
\pretocmd{\section}{%
	\stepcounter{tocsectioncount}%
}{}{}

\pretocmd{\chapter}{%
	\setcounter{tocsectioncount}{0}%
}{}{}

% Check if chapter should be kept together based on section count
\newcommand{\checktocgrouping}{%
	\ifnum\value{tocsectioncount}<8% If chapter has less than 8 sections
		\addtocontents{toc}{\protect\needspace{15\baselineskip}}% Keep it together
	\fi%
}

% ==============================================================================
% End of Page Break Control Module
% ==============================================================================