Trimble Terra

A React component library for Trimble MXP2 web experiences. Built with React 19, TypeScript, and SCSS.

Branch strategy: The react19 branch is the active development branch (v1.x) targeting Next.js projects. The main branch contains the legacy Gatsby-compatible code (v0.x) and is deprecated — do not publish from main.

Storybook

Browse all components, props, and usage examples in the live Storybook:

https://trimble-mxp-terra.netlify.app/

Associated Storybooks

Layouts:

Icons:

Flyout:

Installation

npm install trimble-terra

Peer Dependencies

The following packages must be installed in your application:

npm install react react-dom @trimble-creative-strategy/trimble-mxp-icons react-player image-focus

Usage

Import components directly from the package:

import { SiteNavigation, GlobalFooter, AlertBanner } from "trimble-terra";

function App() {
  return (
    <>
      <SiteNavigation {...navProps} />
      <AlertBanner {...bannerProps} />
      <main>{/* your content */}</main>
      <GlobalFooter {...footerProps} />
    </>
  );
}

Available Components

Components

| Component | Description | | --- | --- | | AlertBanner | Dismissible alert banner for announcements | | Dialog | Modal dialog overlay | | ImageGallery | Responsive image gallery | | LoadingSpinner | Loading state indicator | | ProductDetail | Product detail view | | ProductSummary | Product summary card | | TrialFormStart | Trial signup form | | TrialSummary | Trial information summary |

Layout

| Component | Description | | --- | --- | | LayoutPricingCards | Pricing card grid layout | | Icon | Icon component (re-exported from @trimble-creative-strategy/trimble-mxp-icons) |

Navigation

| Component | Description | | --- | --- | | SiteNavigation | Main site navigation with mega menu support | | Footer | Base footer component | | SectorFooter | Sector-specific footer | | GlobalFooter | Global footer |

Development

# Install dependencies
npm install

# Run Storybook locally
npm run storybook

# Build the library
npm run build

# Lint
npm run lint

# Format check
npm run format:check

Publishing to npm

Releases are automated via GitHub Actions. Pushing a version tag triggers the publish workflow.

Release workflow

1. Make sure you're on the react19 branch with all changes committed and pushed.

2. Bump the version in package.json:

   # Patch release (1.0.0 → 1.0.1)
   npm version patch
   
   # Minor release (1.0.0 → 1.1.0)
   npm version minor
   
   # Major release (1.0.0 → 2.0.0)
   npm version major

   This updates package.json and creates a git tag automatically.

3. Push the commit and tag:

   git push origin react19 --follow-tags

4. The GitHub Actions publish.yml workflow will:

   • Check out the code
   • Install dependencies
   • Run lint and build
   • Verify the tag matches the package.json version
   • Publish to npm

Requirements

• An NPM_TOKEN secret must be configured in the GitHub repository settings (Settings > Secrets and variables > Actions).
• The token needs publish access to the trimble-terra package on npm.

CI

Every push and pull request to react19 runs the CI workflow (lint, format check, build) on Node 20 and 22.

Technical Audit — Known Issues

• K-3 — CommonDescription / CleanDescription duplication (Medium): Nearly identical logic differing only in class names. Merge into one component with a variant prop.
• K-4 — Inline styles instead of SCSS (Medium): CardEcommerce, LayoutPricingCards, PricingCards, SiteNavigationMain, YoutubeVideo, FocusedImageMethods, and others use style={} for layout, backgrounds, and sizing that should live in SCSS.
• K-5 — Pervasive any usage (High): any is used for props, event handlers, refs, and data structures across ~30+ files. Especially dense in SiteNavigation*, LanguageSelector, ProductDetail, LayoutPricingCards, VidyardVideo, and all .jsx files.
• A-1 — onClick on non-interactive elements without keyboard support (High): Multiple <div> and <span> elements have onClick handlers without role="button", tabIndex={0}, or onKeyDown/onKeyUp. ProductOverview.tsx uses <a href="" onClick> instead of <button>.
• A-2 — Missing alt text on images (Medium): App Store / Google Play badge images in TerraLink.tsx, SpecialButton.tsx, and SiteNavigationMobile.tsx lack meaningful alt attributes.
• S-1 — Unsanitized dangerouslySetInnerHTML (High): CMS/prop content rendered via dangerouslySetInnerHTML without visible sanitization in CommonDescription.tsx, functions.tsx, CurrencyList.tsx, ProductSummaryMethods.jsx, FlyoutCart.jsx, checkForDangerouslySet.jsx. Centralize through a sanitizer (e.g., DOMPurify).
• C-2 — Direct DOM manipulation (Medium): CardEcommerce.tsx uses document.querySelector instead of a ref; ImageGalleryMethods.jsx sets body.style.overflow directly; useElementIntersection.ts takes a selector string instead of a ref.
• C-3 — 16 .jsx files remain unconverted (Medium): Slider, NavSearchWrapper, Tooltip, TrialFormStart, ProductSummary, TrialSummary, TrialMethods, TrialSpecifics, ProductSummaryMethods, PricingCards, ImageGallery, ImageGalleryMethods, FlyoutCart, checkForDangerouslySet, CloseIcon, CardEcommerceMethods — all have zero type safety.
• C-4 — Blanket eslint-disable suppresses all warnings (Medium): File-level /* eslint-disable */ in LanguageSelector.tsx, SiteNavigationMain.tsx, CartNavMenu.tsx, FlyoutCart.jsx, FlyoutCartComponent.tsx, QuantityTracker.stories.tsx, Video.tsx.
• C-6 — Console statements in production code (Low): YoutubeVideo.tsx (console.warn) and CardEcommerceMethods.jsx (console.error) will fire in consumers' production builds.
• C-7 — Duplicate ImageGallery component names (Medium): Two separate ImageGallery implementations exist at src/component/ImageGallery/ and src/component/ProductDetail/ImageGallery/, causing confusion and potential import mistakes.