%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% FILE    : macros.tex
% SUBJECT : File to hold the macros defined in the portal project.
% AUTHOR  : (C) Copyright 2018 by Locusworks
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%------------
% New Commands
% ------------

\newcolumntype{L}[1]{>{\raggedright\let\newline\\\arraybackslash\hspace{0pt}}p{#1}}
\newcolumntype{C}[1]{>{\centering\let\newline\\\arraybackslash\hspace{0pt}}p{#1}}
\newcolumntype{R}[1]{>{\raggedleft\let\newline\\\arraybackslash\hspace{0pt}}p{#1}}

% Add commands in alphabetical order.
\newcommand{\command}[1]{\texttt{#1}}    % For formatting commands.
\newcommand{\filename}[1]{\texttt{#1}}   % For formatting file names.
\newcommand{\newterm}[1]{\textit{#1}}    % For formatting terms when they are first introduced.
\newcommand{\bold}[1]{\textbf{#1}}       % For bold font
\newcommand{\italic}[1]{\textit{#1}}     % For italic font
\newcommand{\nn}[0]{\newline\newline}    % for double space
\newcommand{\portal}{Portal\xspace}             % For formatting ``Portal.''
\newcommand{\Client}{\portal Client\xspace}
\newcommand{\Server}{\portal Server\xspace}

\newcommand{\Blue}[1]{\textcolor{blue}{#1}}
\newcommand{\Gray}[1]{\textcolor{gray}{#1}}
\newcommand{\Red}[1]{\textcolor{red}{#1}}

% Keep parameter descriptions in the surrounding list so they can wrap and
% continue onto another page, including nested parameter lists.
\newcommand{\Required}[2]{\texttt{\bold{\Red{#1}}}: #2}
\newcommand{\Optional}[2]{\texttt{\bold{\Gray{#1}}}: #2}

% Reserve room for a sample heading and its first few lines.
\newcommand{\SampleSpace}{%
  \ifdim\dimexpr\pagegoal-\pagetotal\relax<6\baselineskip
    \newpage
  \fi
}

% Full-width samples allow long JSON responses to paginate naturally.
\newcommand{\ApiData}[2]{%
  \par\medskip\SampleSpace\noindent\bold{Sample Request}\par\nopagebreak
  #1\par\medskip\SampleSpace\noindent\bold{Sample Response}\par\nopagebreak
  #2\par\medskip
}

% Versions match the project POMs, Spring Boot BOM, frontend lockfile and Jenkinsfile.
\newcommand{\locusworksCommonsVersion}{3.0.1-RELEASE\xspace}
\newcommand{\JavaVersion}{21\xspace}
\newcommand{\MavenVersion}{3.9.16\xspace}
\newcommand{\AngularVersion}{22.1.5\xspace}
\newcommand{\AngularCliVersion}{22.1.7\xspace}
\newcommand{\SpringBootVersion}{4.1.1\xspace}
\newcommand{\SpringVersion}{7.0.9\xspace}
\newcommand{\NodeVersion}{24.20.0\xspace}
\newcommand{\NpmVersion}{12.0.2\xspace}
\newcommand{\HibernateVersion}{7.4.5.Final\xspace}
\newcommand{\FlywayVersion}{13.5.0\xspace}
\newcommand{\HtwoVersion}{2.4.240\xspace}
\newcommand{\MySQLVersion}{8.4 or newer\xspace}
\newcommand{\MySQLConnectorVersion}{26.7.0\xspace}
\newcommand{\TomcatVersion}{11.0.25\xspace}
\newcommand{\QuartzVersion}{2.5.2\xspace}
\newcommand{\JSchVersion}{2.28.7\xspace}
\newcommand{\JGitVersion}{7.7.1.202607240634-r\xspace}

\let\Oldsection\section
\renewcommand{\section}{\FloatBarrier\Oldsection}

\let\Oldsubsection\subsection
\renewcommand{\subsection}{\FloatBarrier\Oldsubsection}

\let\Oldsubsubsection\subsubsection
\renewcommand{\subsubsection}{\FloatBarrier\Oldsubsubsection}


% Metadata tables account for padding and borders. The body remains outside
% the table so long procedures and parameter lists can break across pages.
\newenvironment{apimethod}[4]
 {\par\medskip\noindent
  \begin{tabular}{|L{\dimexpr.27\linewidth-2\tabcolsep-1.5\arrayrulewidth\relax}|L{\dimexpr.73\linewidth-2\tabcolsep-1.5\arrayrulewidth\relax}|}\hline
    \multicolumn{2}{|p{\dimexpr\linewidth-2\tabcolsep-2\arrayrulewidth\relax}|}{\bold{#1}}\\\hline
    Endpoint URL & \command{#2}\\\hline
    Method & #3\\\hline
    Requires Authentication & #4\\\hline
  \end{tabular}\par\nobreak\smallskip
  \noindent\bold{Parameters}\par\nopagebreak
 }{\par\medskip}

\newenvironment{usecase}[3]
 {\par\medskip\noindent
  \begin{tabular}{|L{\dimexpr.15\linewidth-2\tabcolsep-1.5\arrayrulewidth\relax}|L{\dimexpr.85\linewidth-2\tabcolsep-1.5\arrayrulewidth\relax}|}\hline
    \multicolumn{2}{|p{\dimexpr\linewidth-2\tabcolsep-2\arrayrulewidth\relax}|}{\bold{#1}}\\\hline
    Actor & #2\\\hline
    Context & #3\\\hline
  \end{tabular}\par\nobreak\smallskip
  \noindent\bold{Action}\par\nopagebreak
 }{\par\medskip}