gaia-ui

Shared UI shell components for GAIA-based projects. Built on top of Mantine — bring your own Mantine install.

Installation

npm install @converge-cloudops/gaia-ui

Peer dependencies

npm install [email protected] [email protected] @mantine/[email protected] @mantine/[email protected] @tabler/[email protected]
# required for navigation links (GaiaNavbar uses useLocation internally):
npm install [email protected]

Import the stylesheet

import "@converge-cloudops/gaia-ui/styles.css";

Quick example

import "@mantine/core/styles.css";
import "@converge-cloudops/gaia-ui/styles.css";

import { MantineProvider, createTheme } from "@mantine/core";
import { createBrowserRouter, RouterProvider, Outlet } from "react-router";
import { GaiaShellLayout } from "@converge-cloudops/gaia-ui";
import { IconLayoutDashboard, IconChartBar } from "@tabler/icons-react";

const theme = createTheme({
  colors: {
    convergeTeal: [
      "#e6fafa",
      "#d0f2f2",
      "#a1e4e4",
      "#6ed6d6",
      "#3ecaca",
      "#20bfbf",
      "#0db8b8",
      "#00a0a0",
      "#008f8f",
      "#007b7b",
    ],
  },
  primaryColor: "convergeTeal",
});

const sections = [
  {
    title: "Dashboard",
    links: [
      { icon: IconLayoutDashboard, label: "Overview", link: "/dashboard" },
      { icon: IconChartBar, label: "Analytics", link: "/dashboard/analytics" },
    ],
  },
];

function AppLayout() {
  return (
    <GaiaShellLayout
      headerProps={{
        title: "GAIA",
        menuGroups: [
          {
            label: "Tropos",
            items: [{ label: "Overview", path: "/tropos" }],
          },
        ],
      }}
      navbarProps={{
        sections,
        resolveSection: () => "Dashboard",
      }}
    >
      <Outlet />
    </GaiaShellLayout>
  );
}

const router = createBrowserRouter([
  {
    element: <AppLayout />,
    children: [{ path: "/dashboard", element: <div>Overview</div> }],
  },
]);

export default function App() {
  return (
    <MantineProvider theme={theme}>
      <RouterProvider router={router} />
    </MantineProvider>
  );
}

The convergeTeal custom color is required — active and hovered nav links use this token.

Documentation

Full documentation is in the documentation/ folder:

• Getting Started — peer deps, CSS import, PostCSS setup, convergeTeal theme config
• GaiaShellLayout — full shell in one component
• GaiaHeader — top header bar
• GaiaNavbar — left sidebar navigation
• NavbarLinksGroup — nav link primitive
• GaiaShellProvider — context provider for user and remote configs
• GaiaShellContext — context types and hooks (useGaiaShellContext, useGaiaRemoteConfig)
• createRemoteBaseQuery — RTK Query base query with a mutable base URL
• createRemoteConfigProvider — wires remote URL from context into an RTK Query API
• API Reference — all exported TypeScript types

Development

npm run build        # one-off build
npm run build:watch  # rebuild on change
npm run typecheck    # type check without emitting

Publishing

npm run prepublishOnly  # cleans and rebuilds
npm publish