React Components

What is React?

React is an open-source JavaScript library developed by Facebook for building user interfaces, particularly single-page applications where a dynamic and responsive experience is important. It allows developers to create reusable UI components that efficiently update and render based on changing data.

React uses a component-based architecture, where the UI is broken into small, self-contained pieces called components. Each component manages its own state and renders based on that state and its inputs (called props). React uses a virtual DOM - an in-memory representation of the real DOM - to optimize updates. When data changes, React efficiently computes the minimal set of changes and applies them to the actual DOM, improving performance and responsiveness.

Why This Project Uses React

This documentation site uses React because:

Component Reusability: Custom components like <Figure>, <TableVertical>, and <Citation> allow for consistent formatting and easy reuse across multiple documents.
Dynamic Rendering: React enables conditional rendering and logic-based content, which is valuable for development and component-driven pages.
Docusaurus Integration: Docusaurus is built on React, so using React components fits naturally with the framework and extends its capabilities.

By leveraging React, the documentation becomes more modular, maintainable, and interactive, aligning with modern web development standards.

How React Components are Styled for This Project

All React components in this project are styled using Tailwind CSS, a utility-first CSS framework that allows for rapid and consistent UI development. Rather than writing separate CSS classes or stylesheets, styles are applied directly via Tailwind utility classes within each component's JSX.

This approach promotes consistency, reduces the need for custom CSS, and makes it easy to manage responsive layouts, theming, and typography. Custom design tokens - such as font sizes, colors, and breakpoints - are defined in tailwind.config.js and reused across components to ensure alignment with USACE branding and Groundwork standards.

Where appropriate, utility classes are combined with conditionally applied class names (e.g., for dark mode or responsive behavior), and semanding Tailwind tokens like text-normal, font-usace, or bg-sidebar-bg are used in place of raw values for better readability and maintainability.

Examples: Styling React Components with Tailwind CSS

FigureNoRef

import "../css/custom.css";

const FigureNoRef = ({ src, alt, width = "80%" }) => {
  return (
    <figure className="w-full ml-0 mr-auto my-[1em] py-5 justify-items-start border-y border-border-color">
      <img
        src={`/RMC-Software-Documentation/${src}`}
        alt={alt}
        className="h-auto block"
        style={{ maxWidth: width }}
      />
    </figure>
  );
};

export default FigureNoRef;

Tailwind Class	Vanilla CSS Equivalent
w-full	width: 100%;
ml-0	margin-left: 0;
mr-auto	margin-right: auto;
my-[1em]	margin-top: 1em; margin-bottom: 1em;
py-5	padding-top: 1.25rem; padding-bottom: 1.25rem;
justify-items-start	justify-items: start; (grid containers only)
border-y	border-top: 1px solid; border-bottom: 1px solid;
border-border-color	border-color: var(--border-color);

Tailwind Class	Vanilla CSS Equivalent
h-auto	height: auto;
block	display: block;
style={{ maxWidth: width }}	max-width: 80%; (or passed via prop)

Button

import React from "react";

const baseClasses = `
  px-4 py-[10px]
  bg-ifm-primary-dark
  text-font-color-inverse
  rounded-md
  font-bold
  text-1-0
  no-underline
  inline-block
  transition-colors
  duration-300
  ease-in-out
  border-none
  cursor-pointer
  hover:bg-[#6799ab]
  hover:text-font-color
  hover:no-underline
  disabled:opacity-60
  disabled:cursor-not-allowed
  dark:hover:bg-[#003e53]
`;

export default function Button({
  children,
  onClick,
  href,
  to,
  className = "",
  ...props
}) {
  const classes = `${baseClasses} ${className}`.replace(/\s+/g, " ");

  if (href || to) {
    return (
      <a
        href={href || to}
        className={classes}
        target={href ? "_blank" : undefined}
        rel={href ? "noopener noreferrer" : undefined}
        {...props}
      >
        {children}
      </a>
    );
  }

  return (
    <button onClick={onClick} className={classes} {...props}>
      {children}
    </button>
  );
}

Tailwind Class	Vanilla CSS Equivalent
px-4	padding-left: 1rem; padding-right: 1rem;
py-[10px]	padding-top: 10px; padding-bottom: 10px;
bg-ifm-primary-dark	background-color: var(--ifm-color-primary-dark);
text-font-color-inverse	color: var(--font-color-inverse);
rounded-md	border-radius: 0.375rem;
font-bold	font-weight: 700;
text-1-0	font-size: 1rem;
no-underline	text-decoration: none;
inline-block	display: inline-block;
transition-colors	transition-property: color, background-color, border-color, text-decoration-color, fill, stroke;
duration-300	transition-duration: 300ms;
ease-in-out	transition-timing-function: ease-in-out;
border-none	border: none;
cursor-pointer	cursor: pointer;
hover:bg-[#6799ab]	background-color on hover: #6799ab;
hover:text-font-color	color on hover: var(--font-color);
hover:no-underline	text-decoration on hover: none;
disabled:opacity-60	opacity: 0.6 when disabled;
disabled:cursor-not-allowed	cursor: not-allowed when disabled;
dark:hover:bg-[#003e53]	background-color on hover (dark mode): #003e53;

React Components in This Project

This project includes several custom React components that enhance the documentation experience. These components are designed to be reusable and provide consistent formatting across different pages. The following sections describe the key components available to developers.

NOTICE

React components should not be altered, removed, or added to this project. To request changes, additions, or improvements, please contact a site administrator.

Bibliography

Overview and Functionality

The <Bibliography> component is a dynamic React component used to render a properly ordered and formatted list of citations within a documentation page. It automatically loads citation metadata from a bib.json file and aligns each entry to the citation numbers defined in the corresponding counters.json file.

This component is intended for reports and technical documentation where references must be accurate, consistent, and easily maintained across versions.

Functionality includes:

Automatically determines the bibliography file path based on the current page URL and active reportId from context.
Loads two JSON files:
- bib.json – Contains full citation metadata.
- counters/{reportId}.json – Maps citationKeys to citation numbers.
Merges and sorts citations in proper numerical order ([1], [2], etc.).
Formats author lists based on count:
- 1 author: Author A
- 2 authors: Author A and Author B
- 3 authors: Author A, Author B, and Author C
- 3 authors: Author A, et al.
Outputs an ordered list (<ol>) of styled citations:
- Italicizes titles
- Links DOIs and URLs
- Handles fields like journal, volume, pages, organization, institution, and more

tip

Store all bibliography files in /static/bibliographies/ and follow the name convention laid out in Static Folder to allow the component to resolve them automatically.

Props

The component does not accept any props. Instead, it uses two React Context hooks internally:

Source	Description
useLocation()	Extracts the current documentation path to construct the bib.json file path
useReportId()	Resolves the active reportId to locate the corresponding counters.json

Example Usage

To render a bibliography section in a documentation page, simply import and place the component in your References page:

import Bibliography from "@site/src/components/Bibliography";

<Bibliography />;

Button

Overview and Functionality

The <Button> component renders a consistent, styled button or link using Tailwind CSS utility classes. It supports both clickable buttons and navigation links, making it reusable across the documentation site.

Functionality includes:

Applies a shared set of Tailwind utility classes for layout, color, and interaction styling
Renders as either:
- a <button> when onClick is provided (e.g., for form actions or events)
- an <a> when href or to is provided (for navigation or external links)
Accepts additional utility classes via the className prop
Handles hover, focus, and disabled states with smooth transitions
Supports dark mode via dark:hover:* utility classes

note

The component relies on a centralized baseClasses string that defines all default styles using Tailwind. These styles include spacing, font, color, and transition behavior.

Props

Prop	Type	Required	Description
children	ReactNode	Yes	Content inside the button (e.g., label or icon)
onClick	function	No	Click handler for button behavior
href	string	No	Optional URL for navigation (renders as `<a>`)
to	string	No	Alias for `href` (used interchangeably)
className	string	No	Additional class names to override or extend styling

caution

You must provide either an onClick or an href/to prop. If neither is present, the component will render a button element with no behavior.

Example Usage

import Button from "@site/src/components/Button";

// As a clickable button
<Button onClick={() => alert("Clicked!")}>
  Submit
</Button>

// As a navigation link
<Button href="/docs/introduction">
  Read More
</Button>

Citation

Overview and Functionality

The <Citation> component is a lightweight inline React component that displays a numbered reference (e.g., [3]) tied to a citation entry in the page’s bibliography. It ensures in-text references are dynamically synchronized with the citation order defined in the associated counters.json file.

Functionality includes:

Automatically determines the citation number based on the current page’s path and the active reportId (via useReportId()).
Loads the following resources:
- counters/{reportId}.json – Maps citationKey to its assigned citation number
- bib.json – Ensures the citation actually exists in the bibliography file
Tracks which citations are used on each page via getUsedCitations(pathname)
Renders a bracketed, clickable reference:
- [1], [2], etc.
- Links to the matching entry in the <Bibliography /> component (via #footnote-{citationKey})

warning

The component assumes a one-to-one match between citationKey in bib.json and the counters.json file. If the key is missing from the counters file, the reference will display as [?].

Props

Prop	Type	Required	Description
citationKey	string	Yes	A unique key identifying the citation in both bib.json and counters.json.

Example Usage

To insert an inline citation in your documentation, pass the citationKey to the component:

import Citation from '@site/src/components/Citation';

This guidance is consistent with earlier findings <Citation citationKey="USACE2023c" />.

CitationFootnote

Overview and Functionality

The <CitationFootnote> component renders a list of full citation footnotes at the bottom of a documentation page, based on which <Citation /> references were used. It ensures that only citations actually referenced in the content are displayed, and that they appear in correct numerical order.

Functionality includes:

Retrieves the current page path and active reportId to resolve:
- bib.json – Contains full metadata for all potential citations
- counters/{reportId}.json – Maps citationKeys to their assigned citation numbers
Uses getUsedCitations(pathname) from the <Citation /> module to determine which citation keys are used on the current page
Sorts citations in ascending numerical order before rendering
Formats author lists and fields such as:
- author, title, journal, volume, pages, publisher, organization, institution, doi, url, etc.
Wraps each entry in a list item with an ID like #footnote-USACE2023c for in-page linking from <Citation />

warning

The component will not render anything if no <Citation /> components were used on the page. It only displays footnotes for referenced citations.

Props

The component does not accept any props. Instead, it uses two React Context hooks internally:

Source	Description
useLocation()	Extracts the current documentation path to construct the bib.json file path
useReportId()	Resolves the active reportId to locate the corresponding counters.json

Example Usage

Place <CitationFootnote /> at the bottom of your .mdx file to display footnotes for all citations used in the page:

import CitationFootnote from "@site/src/components/CitationFootnote";

<CitationFootnote />;

DocumentMetadata

Overview and Functionality

The <DocumentMetadata> component displays structured report metadata in a tabular format at the top or bottom of a documentation page. It is designed to be used in the 00-document-info.mdx page to present key contextual information about the document—such as title, authorship, abstract, and citation guidance—in a clean and consistent layout.

Functionality includes:

Renders a table with defined metadata fields:
- Report Date, Type, Title, Subtitle, Author(s), Abstract, Acknowledgements, Subject Terms, Responsible Person, and How to Cite This Document
Accepts metadata values as a single metadata object via props
Handles arrays (reportAuthors, reportSubjectTerms) with custom formatting:
- Authors are joined with ;
- Subject terms are joined with ,
Filters out any undefined or empty values to avoid displaying blank rows
Renders text content as raw HTML using dangerouslySetInnerHTML to allow styled input (e.g., italics, superscripts)

warning

This component does not handle data fetching. Metadata must be passed as a complete object from the parent .mdx file or component.

Props

Prop	Type	Required	Description
metadata	object	Yes	An object containing key-value pairs for document metadata. See below.

The metadata object should be formatted as frontMatter in the .mdx file, typically defined at the top of the document.

Expected Metadata Fields

Key	Type	Description
reportDate	string	Date the report was finalized
reportType	string	Document type (e.g., Technical Report, User Guide)
reportTitle	string	Main title of the document
reportSubTitle	string (optional)	Optional subtitle or secondary title
reportAuthors	string \| array	Author name(s), either as a single string or array
reportAbstract	string	Summary of the document’s content
reportAcknowledgments	string (optional)	Credits for contributions or support
reportSubjectTerms	string \| array	Keywords or indexing terms
responsiblePersonName	string (optional)	Contact person for the document
responsiblePersonNumber	string (optional)	Phone number or contact ID
citationGuide	string	How to properly cite the document

caution

The component uses dangerouslySetInnerHTML to render all values. Be sure that all strings passed to metadata are sanitized or trusted content.

Example Usage

To display metadata at the beginning of a page:

import DocumentMetadata from '@site/src/components/DocumentMetadata';

---
title: Document Info
reportDate: May 2025
reportType: Computer Program Document
reportTitle: RMC Filter Evaluation (Continuation) Toolbox
reportSubTitle: RMC Internal Erosion Suite
reportAuthors: ["Adam Gohs, Risk Management Center"]
reportAbstract: The spreadsheet tools contained in this toolbox assess the particle retention and permeability criteria for filter materials. It includes modern no-erosion filter design criteria, the Foster and Fell (2001) method for filters that do not meet modern filter design criteria, and the Fell et al. (2008) method for “continuing erosion” condition for constricted exits.
reportSubjectTerms: ["Internal erosion", "continuation", "filter evaluation", "filter design criteria"]
responsiblePersonName: Tim O'Leary
responsiblePersonNumber: 502-315-6599
citationGuide: "A. C. Gohs, <i>RMC Filter Evaluation (Continuation) Toolbox Technical Manual</i>, Lakewood, CO: U.S. Army Corps of Engineers, Risk Management Center, 2025. Accessed on <i>{enter current date here}</i>."
---

<DocumentMetadata metadata={frontMatter} />

Equation

Overview and Functionality

The <Equation> component renders LaTeX equations using KaTeX and optionally displays equation numbers based on the equationKey. It supports both inline and block-level equations and ensures automatic numbering via a shared counters.json file scoped to the current reportId.

Functionality includes:

Fetches the current reportId from context (useReportId()).
Loads the corresponding counters file:
- /RMC-Software-Documentation/counters/{reportId}.json
Matches the provided equationKey to retrieve the associated equationNumber.
Displays the equation with or without a number depending on the inline prop.
Renders equations using:
- <InlineMath /> from react-katex for inline formatting
- <BlockMath /> from react-katex for centered display with numbering

note

All equations are rendered with KaTeX, which supports a large subset of LaTeX. Be sure your expressions are KaTeX-compatible.

Props

Prop	Type	Required	Description
equationKey	string	Yes	Unique key used to match the equation in counters/{reportId}.json.
equation	string	Yes	A valid LaTeX string representing the equation to be rendered.
inline	boolean	No	If true, renders the equation inline (default: false, renders as block).

caution

If equationKey is not found in the counters file, the equation will still render but without a number. Check the console for warnings if a number does not appear.

Example Usage

To render a numbered equation in block format:

import Equation from "@site/src/components/Equation";

<Equation equationKey="eqn_energy_balance" equation="E = mc^2" />;

To render an inline equation without a number:

<Equation
  equationKey="eqn_energy_balance"
  equation="E = mc^2"
  inline={true}>
/>

EquationNoRef

Overview and Functionality

The <EquationNoRef> component renders LaTeX-based equations using KaTeX, but without reference numbers. It is ideal for displaying supporting mathematical expressions where numbering is unnecessary, such as intermediate steps or formulas mentioned in passing.

Functionality includes:

Uses the KaTeX library to render mathematical content.
Supports both inline and block display modes via the inline prop:
- Inline mode renders within a line of text.
- Block mode renders centered on its own line.
Requires only the LaTeX equation string — no reportId, equationKey, or counters integration.

warning

This component is purely visual. It does not manage equation numbering, anchors, or references. Use <Equation /> for numbered equations.

Props

Prop	Type	Required	Description
equation	string	Yes	A LaTeX-compatible string representing the equation.
inline	boolean	No	If true, renders inline; if false, renders as a block. Default is true.

info

This component does not fetch or display equation numbers. If you need an equation to be numbered and cross-referenced, use <Equation /> instead.

Example Usage

To render an inline equation:

import EquationNoRef from "@site/src/components/EquationNoRef";

<EquationNoRef equation="a^2 + b^2 = c^2" />;

To render the same equation as a centered block:

<EquationNoRef equation="a^2 + b^2 = c^2" inline={false} />

Best Practice

Use <EquationNoRef> for simple, unnumbered equations, when displaying intermediate steps in derivations, or short equations within text.

EquationReference

Overview and Functionality

The <EquationReference> component is used to dynamically display a reference to a numbered equation based on its equationKey. It retrieves the equation number from a counters file scoped to the current reportId and renders a formatted string like Equation 3.

This is useful for referring to previously defined equations elsewhere in the documentation without hardcoding numbers.

Functionality includes:

Retrieves the current reportId from context (useReportId()).
Loads the appropriate counters.json file from:
- /RMC-Software-Documentation/counters/{reportId}.json
Looks up the equation number corresponding to the provided equationKey.
Renders a simple, styled text label like Equation 5.

note

This component does not render the equation itself—only a textual reference to its number. Use it in conjunction with <Equation /> to create cross-references.

Props

Prop	Type	Required	Description
equationKey	string	Yes	Unique identifier used to retrieve the equation number from the counters file.

caution

If the equationKey is not found or the counters file cannot be loaded, the component will fallback to Loading.... Console warnings will be shown to help with debugging.

Example Usage

Use <EquationReference /> inline to refer to a previously displayed equation:

import EquationReference from '@site/src/components/EquationReference';

As shown in <EquationReference equationKey="eqn_energy_balance" />, energy is conserved...

Figure

Overview and Functionality

The <Figure> component is used to embed images within documentation and automatically apply figure numbering using a centralized counters.json file. It is ideal for technical reports that require consistently numbered figures across pages and references.

Functionality includes:

Retrieves the current reportId from context using useReportId()
Loads the associated counters.json file from:
- /RMC-Software-Documentation/counters/{reportId}.json
Matches the provided figKey to the figure number in the counters file
Renders:
- An image using the src path
- A caption with automatic numbering: Figure 3: Caption text

info

This component handles figure numbering and display in block format. To insert a figure inline with text, use the <FigureInline /> component.

This component handles figure numbering and display. To insert an inline figure reference (e.g., "see Figure 3"), use the <FigureReference /> component.

Props

Prop	Type	Required	Description
figKey	string	Yes	Unique identifier for the figure in the counters file
src	string	Yes	Path to the image file relative to the /RMC-Software-Documentation/ root
alt	string	Yes	Alternative text for the image (used for accessibility and SEO)
caption	string	Yes	Text that appears below the figure as its description

caution

If figKey is not found or the counters file cannot be loaded, the component will fallback to Loading.... Console warnings will be shown to help with debugging.

Example Usage

import Figure from "@site/src/components/Figure";

<Figure
  figKey="fig_infiltration_diagram"
  src="figures/infiltration-diagram.png"
  alt="Cross-sectional view of infiltration process"
  caption="Conceptual model illustrating infiltration through embankment materials."
/>;

FigureInline

Overview and Functionality

The <FigureInline> component is a simple, unnumbered image renderer used to display small images inline with surrounding content. It is best suited for icons, schematic thumbnails, or other visuals that do not require figure numbers or captions.

Functionality includes:

Constructs the image path by prepending /RMC-Software-Documentation/ to the provided src.
Applies inline styling via the figure-inline CSS class to ensure the image flows with surrounding text.
Does not include captions, alt text, or numbering.

note

This component is strictly visual and is not included in the automatic figure numbering system. Use <Figure /> if you need a captioned and numbered image.

Props

Prop	Type	Required	Description
src	string	Yes	Relative path to the image (from the /RMC-Software-Documentation/ root)

caution

This component does not support alt text. If accessibility is a requirement, use the <img> tag directly or extend this component.

Example Usage

import FigureInline from '@site/src/components/FigureInline';

Here is a comparison chart <FigureInline src="figures/chart-thumbnail.png" /> that shows the performance differences between models.

FigureReference

Overview and Functionality

The <FigureReference> component is used to dynamically insert a numbered reference to a figure within a sentence or paragraph. It fetches the correct figure number from the centralized counters.json file using the provided figKey, and renders text such as Figure 5.

Functionality includes:

Retrieves the current reportId from context via useReportId()
Loads the counters file from:
- /RMC-Software-Documentation/counters/{reportId}.json
Locates the figure number using the provided figKey
Renders a simple inline label like Figure 2

note

This component is useful for cross-referencing figures from elsewhere in the document. It does not render the image itself—only the figure number.

Props

Prop	Type	Required	Description
figKey	string	Yes	Unique key for the figure, matching an entry in the counters file

caution

If the figKey is not found or the counters file fails to load, the output will display Loading.... Console warnings will indicate the missing reference.

Example Usage

Use <FigureReference /> inline to refer to a previously inserted <Figure />:

import FigureReference from '@site/src/components/FigureReference';

As shown in <FigureReference figKey="fig_infiltration_diagram" />, infiltration occurs vertically through the embankment core...

NavContainer

Overview and Functionality

The <NavContainer> component provides a consistent layout for displaying navigation and version selection controls at the top of a documentation page. It wraps two subcomponents:

<NavLink />: A navigational link back to a parent page or section.
<VersionSelector />: A dropdown for selecting available document versions.

This layout ensures users always have quick access to both the document structure and alternate versions of the current content.

Functionality includes:

Displays a styled navigation link using the provided link and linkTitle.
Displays a version selector dropdown based on the document prop.
Organizes both elements using a flexible container layout styled via nav-container.css.

note

This component is a layout utility and does not manage routing or version state itself. It delegates those tasks to <NavLink /> and <VersionSelector />.

Props

Prop	Type	Required	Description
link	string	Yes	The relative path to the parent or target page for navigation
linkTitle	string	Yes	The text label for the navigation link (e.g., "Back to Overview")
document	string	Yes	The identifier used by <VersionSelector /> to determine available versions

caution

All three props are required. Omitting any of them may result in broken layout or missing navigation elements.

Example Usage

import NavContainer from "@site/src/components/NavContainer";

<NavContainer
  link="/docs/project-x/overview"
  linkTitle="← Back to Project Overview"
  document="project-x"
/>;

NavLink

Overview and Functionality

The <NavLink> component renders a styled navigational link that points to a related page within your Docusaurus site. It is typically used to provide a “Back to…” or “Return to…” link at the top of a documentation page, and is often embedded inside <NavContainer />.

Functionality includes:

Resolves the base URL dynamically using Docusaurus’ useBaseUrl() hook.
Wraps the destination in a <Link /> component for proper SPA navigation.
Renders left-pointing arrow (←) followed by a custom label from linkTitle.
Styled via the shared nav-and-print.css class set.

note

This component is purely presentational. It does not conditionally render or validate whether the target path exists.

Props

Prop	Type	Required	Description
link	string	Yes	The relative path to the destination page (e.g., /docs/project-x/intro)
linkTitle	string	Yes	The text displayed next to the arrow (e.g., Back to Overview)

caution

Make sure link is a valid internal route in your Docusaurus project. External URLs will not work properly here.

Example Usage

import NavLink from "@site/src/components/NavLink";

<NavLink
  link="/docs/project-x/overview"
  linkTitle="Back to Project Overview"
/>;

TableAcronyms

Overview and Functionality

The <TableAcronyms> component was created specifically to display acronyms and their long-form definitions in a static, two-column vertical table. This component is to be used in the Acronym appendix of documents.

Functionality includes:

Accepts a list of column headers and column data arrays as props.
Dynamically computes the number of rows based on the length of the first column.
Renders a simple HTML <table> with:
- One <thead> row for column labels
- Multiple <tbody> rows built from corresponding items in each column

note

This component renders a fixed-layout table. It does not support dynamic sorting, filtering, or merging of cells.

Props

Prop	Type	Required	Description
headers	string[]	Yes	An array of column labels (typically ["Acronym", "Definition"])
columns	array[]	Yes	An array of arrays, where each inner array represents one column of values

caution

All columns must have the same number of rows. Empty cells will be padded automatically, but uneven arrays may produce unexpected results.

Example Usage

import TableAcronyms from "@site/src/components/TableAcronyms";

<TableAcronyms
  headers={["Acronym", "Definition"]}
  columns={[
    ["RMC", "USACE", "FEMA"],
    [
      "Risk Management Center",
      "U.S. Army Corps of Engineers",
      "Federal Emergency Management Agency",
    ],
  ]}
/>;

TableHorizontal

Overview and Functionality

The <TableHorizontal> component displays a horizontal table where headers are listed vertically in the first column, and corresponding row data is arranged to the right. This format is useful for comparing attribute values side-by-side across multiple items.

It also supports automatic table numbering via a central counters.json file, ensuring consistent references across documents.

Functionality includes:

Loads the current reportId from context using useReportId()
Retrieves the table number using tableKey from:
- /RMC-Software-Documentation/counters/{reportId}.json
Displays:
- A caption with the resolved table number
- A horizontal layout where each row starts with a header and is followed by values
Supports inline HTML formatting inside cells using dangerouslySetInnerHTML

note

This component is designed for transposed tables—use it when each row represents a field and each column represents a different scenario or category.

This component handles table numbering and display. To insert an inline table reference (e.g., "see Table 3"), use the <TableReference /> component.

Props

Prop	Type	Required	Description
tableKey	string	Yes	Unique key used to match the table in the counters.json file
headers	string[]	Yes	Array of header labels for each row (first column of the table)
rows	array[]	Yes	2D array of cell values (one array per row, excluding the header column)
alt	string	Yes	Alternative text for accessibility and screen readers
caption	string	Yes	Descriptive text shown under the table number

caution

Make sure the number of headers matches the number of rows. Mismatches will result in misaligned rows or rendering issues.

If tableKey is not found or the counters file cannot be loaded, the component will fallback to Loading.... Console warnings will be shown to help with debugging.

Example Usage

import TableHorizontal from "@site/src/components/TableHorizontal";

<TableHorizontal
  tableKey="overtopping-depth-duration"
  headers={["Overtopping Depth (ft)", "Overtopping Duration (hrs)"]}
  rows={[
    ["0", "0.5", "1.0", "1.5", "2.0"],
    ["0", "2", "4", "8", "13", "20"],
  ]}
  alt="Overtopping depth and duration comparison"
  caption="Overtopping durations in hours for given peak overtopping depths in feet."
/>;

TableReference

Overview and Functionality

The <TableReference> component is used to insert dynamic references to tables elsewhere in the documentation. When given a tableKey, it fetches the corresponding table number from the centralized counters.json file associated with the current reportId and displays it inline as Table 4, for example.

This helps maintain consistent, automatically updated references across pages—even if table numbering changes during editing.

Functionality includes:

Retrieves the active reportId from context via useReportId()
Loads table metadata from:
- /RMC-Software-Documentation/counters/{reportId}.json
Locates and displays the table number that matches the given tableKey
Renders a styled inline reference like Table 5

note

This component is used for text references only. It does not render the full table. To display an actual table, use a component like <TableHorizontal /> or <TableVertical />.

Props

Prop	Type	Required	Description
tableKey	string	Yes	Unique key used to locate the table number in the counters.json file

caution

If tableKey is not found or the counters file cannot be loaded, the component will fallback to Loading.... Console warnings will be shown to help with debugging.

Example Usage

import TableReference from '@site/src/components/TableReference';

The material properties shown in <TableReference tableKey="table_material_properties" /> illustrate typical values for different
embankment zones.

TableVersionHistory

Overview and Functionality

The <TableVersionHistory> component displays a structured version history table for a document or software application. It is designed to be used in the 00-version-history.mdx page to present version history information about the document - such as version number, date, version update descriptions, modified by, reviewed by, and approved by.

Functionality includes:

Accepts six parallel arrays as props: versions, dates, descriptions, modifiedBy, reviewedBy, and approvedBy
Automatically calculates the total number of rows needed based on the longest column
Displays a static HTML <table> with consistent formatting via static-table-version-history CSS class
Applies title tooltips on reviewer/approver/modifier cells for clarity on hover

note

The table rows are padded automatically if some columns are shorter than others, ensuring visual consistency.

Props

Prop	Type	Required	Description
versions	string[]	Yes	Array of version labels (e.g., "1.0", "2.1")
dates	string[]	Yes	Corresponding array of dates for each version
descriptions	string[]	Yes	Description of what changed in each version
modifiedBy	string[]	Yes	Who modified the document in each version
reviewedBy	string[]	Yes	Who reviewed each version
approvedBy	string[]	Yes	Who approved each version

caution

All arrays must represent parallel data. The table will expand to the longest array and fill empty cells where necessary.

Example Usage

import TableVersionHistory from "@site/src/components/TableVersionHistory";

<TableVersionHistory
  versions={["1.0", "1.1", "2.0"]}
  dates={["2023-05-01", "2023-06-15", "2024-01-10"]}
  descriptions={[
    "Initial release",
    "Minor updates and formatting improvements",
    "Major update with new analysis section",
  ]}
  modifiedBy={["A. Engineer", "B. Analyst", "C. Reviewer"]}
  reviewedBy={["D. Checker", "E. QA", "F. Lead Reviewer"]}
  approvedBy={["G. Manager", "H. Manager", "I. Director"]}
/>;

TableVertical

Overview and Functionality

The <TableVertical> component renders a standard vertical table layout, where column headers appear at the top and data is populated row by row below. It supports complex table structures, including merged header and data cells via rowSpan and colSpan, and it integrates with a counters.json file to provide automatic table numbering.

Functionality includes:

Loads the current reportId from context (useReportId())
Retrieves table number from:
- /RMC-Software-Documentation/counters/{reportId}.json
Renders:
- A multi-row <thead> for flexible column grouping and merging
- A multi-column <tbody> based on column-structured input arrays
Supports colSpan and rowSpan for both headers and data cells
Dynamically applies full-width or partial-width styling using the fullWidth prop

note

This component is ideal for structured engineering, scientific, or technical tables that require precise formatting and automatic numbering.

Props

Prop	Type	Required	Description
tableKey	string	Yes	Unique key used to match the table in the counters.json file
headers	array[][]	Yes	Array of header rows, where each row is an array of { value, colSpan?, rowSpan? } objects
columns	array[][]	Yes	Array of columns, where each column is an array of cell strings or cell objects with value, rowSpan?, and colSpan?
fullWidth	boolean	No	Whether to apply full-width table styling (default: true)
alt	string	Yes	Alternative text for accessibility
caption	string	Yes	Descriptive label shown with the table number

caution

All columns must be the same length. Use empty strings to pad shorter columns to maintain alignment.

Example Usage

import TableVertical from "@site/src/components/TableVertical";

<TableVertical
  tableKey="table_material_classification"
  headers={[
    [
      { value: "Material", rowSpan: 2 },
      { value: "Properties", colSpan: 2 },
    ],
    [
      { value: null },
      { value: "Unit Weight (pcf)" },
      { value: "Permeability (cm/s)" },
    ],
  ]}
  columns={[
    ["Clay", "Sand", "Gravel"],
    ["120", "110", "100"],
    ["1e-7", "1e-4", "1e-2"],
  ]}
  alt="Typical material properties"
  caption="Typical unit weight and permeability values for embankment materials."
/>;

TableVerticalLeftAlign

Overview and Functionality

The <TableVerticalLeftAlign> component is a variant of <TableVertical /> that uses left-aligned styling for all header and data cells. It is ideal for tables with descriptive or text-heavy content where left alignment improves readability.

All functionality and input structure are the same as <TableVertical />, including:

Support for merged headers and data cells (rowSpan, colSpan)
Automatic table numbering using tableKey and reportId
Full-width or partial-width layout via fullWidth

note

This component differs from <TableVertical /> only in visual alignment. It is otherwise interchangeable.

Props

Identical to <TableVertical />:

Prop	Type	Required	Description
tableKey	string	Yes	Key for retrieving table number from the counters.json file
headers	array[][]	Yes	Header rows with { value, colSpan?, rowSpan? } objects
columns	array[][]	Yes	Column-major data format
fullWidth	boolean	No	Enables full-width styling (default: true)
alt	string	Yes	Alt text for screen readers
caption	string	Yes	Descriptive caption shown with table number

Example Usage

import TableVerticalLeftAlign from "@site/src/components/TableVerticalLeftAlign";

<TableVerticalLeftAlign
  tableKey="table_material_classification"
  headers={[
    [
      { value: "Material", rowSpan: 2 },
      { value: "Properties", colSpan: 2 },
    ],
    [
      { value: null },
      { value: "Unit Weight (pcf)" },
      { value: "Permeability (cm/s)" },
    ],
  ]}
  columns={[
    ["Clay", "Sand", "Gravel"],
    ["120", "110", "100"],
    ["1e-7", "1e-4", "1e-2"],
  ]}
  alt="Typical material properties"
  caption="Typical unit weight and permeability values for embankment materials."
/>;

VersionSelector

Overview and Functionality

The <VersionSelector> component renders a dropdown that allows users to switch between different versions of a document. It automatically detects the current version from the URL and updates the browser route when a new version is selected—without requiring a full page reload.

Functionality includes:

Loads available versions for the current document from:
- /RMC-Software-Documentation/versions/versionList.json
Extracts the version segment (e.g., /v1.0/) from the current URL
Updates the URL path when the user selects a different version
Maintains client-side navigation using Docusaurus’ useHistory() and useLocation()

note

This component relies on the presence of a JSON object in versionList.json where each document maps to an array of version strings (e.g., ["v1.0", "v2.1"]).

Props

Prop	Type	Required	Description
document	string	Yes	A unique identifier used to fetch the version list from versionList.json

caution

If document is not provided or not found in the version list, the dropdown will not render and a fallback message will be shown.

Example Usage

import VersionSelector from "@site/src/components/VersionSelector";

<VersionSelector document="rmc-dam-safety-toolbox" />;

What is React?​

Why This Project Uses React​

How React Components are Styled for This Project​

Examples: Styling React Components with Tailwind CSS​

FigureNoRef​

Button​

React Components in This Project​

Bibliography​

Overview and Functionality​

Props​

Example Usage​

Button​

Overview and Functionality​

Props​

Example Usage​

Citation​

Overview and Functionality​

Props​

Example Usage​

CitationFootnote​

Overview and Functionality​

Props​

Example Usage​

DocumentMetadata​

Overview and Functionality​

Props​

Expected Metadata Fields​

Example Usage​

Equation​

Overview and Functionality​

Props​

Example Usage​

EquationNoRef​

Overview and Functionality​

Props​

Example Usage​

EquationReference​

Overview and Functionality​

Props​

Example Usage​

Figure​

Overview and Functionality​

Props​

Example Usage​

FigureInline​

Overview and Functionality​

Props​

Example Usage​

FigureReference​

Overview and Functionality​

Props​

Example Usage​

NavContainer​

Overview and Functionality​

Props​

Example Usage​

NavLink​

Overview and Functionality​

Props​

Example Usage​

TableAcronyms​

Overview and Functionality​

Props​

Example Usage​

TableHorizontal​

Overview and Functionality​

Props​

Example Usage​

TableReference​

Overview and Functionality​

Props​

Example Usage​

TableVersionHistory​

Overview and Functionality​

Props​

Example Usage​

TableVertical​

Overview and Functionality​

Props​

Example Usage​

What is React?

Why This Project Uses React

How React Components are Styled for This Project

Examples: Styling React Components with Tailwind CSS

FigureNoRef

Button

React Components in This Project

Bibliography

Overview and Functionality

Props

Example Usage

Button

Overview and Functionality

Props

Example Usage

Citation

Overview and Functionality

Props

Example Usage

CitationFootnote

Overview and Functionality

Props

Example Usage

DocumentMetadata

Overview and Functionality

Props

Expected Metadata Fields

Example Usage

Equation

Overview and Functionality

Props

Example Usage

EquationNoRef

Overview and Functionality

Props

Example Usage

EquationReference

Overview and Functionality

Props

Example Usage

Figure

Overview and Functionality

Props

Example Usage

FigureInline

Overview and Functionality

Props

Example Usage

FigureReference

Overview and Functionality

Props

Example Usage

NavContainer

Overview and Functionality

Props

Example Usage

NavLink

Overview and Functionality

Props

Example Usage

TableAcronyms

Overview and Functionality

Props

Example Usage

TableHorizontal

Overview and Functionality

Props

Example Usage

TableReference

Overview and Functionality

Props

Example Usage

TableVersionHistory

Overview and Functionality

Props

Example Usage

TableVertical

Overview and Functionality

Props

Example Usage