@upbound/ux

Complex UX components that combine primitives with business logic, API calls, and state management.

Installation

yarn add @upbound/ux
# or
npm install @upbound/ux

Note: This package depends on @upbound/elements and @tanstack/react-query. Make sure to import the elements styles and wrap your application with a QueryClientProvider.

Usage

1. Import Styles (Required)

This package uses components from @upbound/elements, so you must include the base styles:

/* In your main CSS file */
@import '@upbound/elements/styles.css';

Or in JavaScript:

// In your _app.tsx or root layout
import '@upbound/elements/styles.css';

2. Set Up QueryClientProvider (Required)

This package uses TanStack Query for data fetching. Wrap your application with a QueryClientProvider:

// In your _app.tsx or root layout
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient();

function App({ children }) {
  return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
}

3. Configure Framework-Specific Components (Optional)

Components in this package use @upbound/elements primitives which render standard <a> and <img> elements by default. If you're using Next.js and want optimized routing/images, wrap your app with ElementsProvider:

// In your _app.tsx or root layout
import { ElementsProvider } from '@upbound/elements';
import Link from 'next/link';
import Image from 'next/image';

function App({ children }) {
  return (
    <ElementsProvider Link={Link} Image={Image}>
      {children}
    </ElementsProvider>
  );
}

This step is optional — without the provider, all components work with standard HTML elements.

4. Import Components

import { GlobalNav, DocumentationButton, OpenDrawerButton } from '@upbound/ux';

function App() {
  return (
    <GlobalNav
      context={navigationContext}
      navigationProps={{
        left: <OpenDrawerButton />,
        right: <DocumentationButton />,
      }}
    >
      {children}
    </GlobalNav>
  );
}

When to Add Components Here

Add a component to this package if:

1. ✅ It's needed across multiple applications
2. ✅ It's more than a primitive element (button, input, dropdown, etc.)
3. ✅ It wraps primitives with network calls or complex calculations
4. ✅ It contains business logic specific to Upbound products

If your component is a simple, reusable primitive without business logic, consider adding it to @upbound/elements instead.

Available Exports

All exports are available from the main entry point:

import { GlobalNav, CreateCheckoutButton, ... } from '@upbound/ux';

Components

| Export | Description | | ------------------------ | -------------------------------------------------------------------------- | | GlobalNav | Main navigation component with drawer, navigation tree, and upsell support | | GlobalNavCore | Core navigation component without the MainDrawerProvider wrapper | | GlobalNavSystemStatus | System status indicator that fetches and displays Upbound status | | SystemStatusDot | Visual status dot indicator (green/yellow/orange/red/blue) | | CreateCheckoutButton | Button that initiates Stripe checkout session for plan upgrades | | UsageOverTimeAreaChart | Chart component displaying usage metrics over time (area/bar, cumulative) | | DocumentationButton | Navigation link button to Upbound documentation | | FreeCreditsButton | Upsell button with popover for free credits promotion | | OpenDrawerButton | Button that opens the main navigation drawer | | RequestFeatureButton | Button that opens Intercom for feature requests | | ContactUsButton | Button that opens Intercom for support contact |

Hooks & Utilities

| Export | Description | | --------------------------- | ---------------------------------------------------------------------- | | generateNavigationTree | Generates navigation tree structure based on user tier and permissions | | footerLinks | Predefined footer links array for the navigation drawer | | useStatusData | Hook to fetch system status from Upbound status page | | getStatusIndicator | Utility to normalize status indicator strings to SystemStatus type | | computeNonCumulativeUsage | Computes daily (non-cumulative) usage data for charts | | computeCumulativeUsage | Computes cumulative usage data for charts |

Types

| Export | Description | | ----------------------------- | -------------------------------------------------------------------------------------- | | GlobalNavProps | Props for GlobalNav and GlobalNavCore components | | CreateCheckoutButtonProps | Props for CreateCheckoutButton component | | UsageOverTimeAreaChartProps | Props for UsageOverTimeAreaChart component | | FreeCreditsButtonProps | Props for FreeCreditsButton component | | MetricData<T> | Generic type for chart metric data with date and values | | StatusPageResponse | Type for status page API response | | SystemStatus | Union type: 'none' \| 'critical' \| 'major' \| 'minor' \| 'maintenance' \| 'unknown' | | SystemStatusDotProps | Props for SystemStatusDot component |

Development

Develop components in isolation with Storybook:

cd packages/ux
yarn storybook

Add a .stories.tsx file for each component to enable isolated development with mocked API calls and providers.

Build the package:

yarn build

Dependencies

This package depends on:

• @upbound/elements — Primitive UI components and styles
• @upbound/api — API client and types
• @upbound/utils — Shared utility functions
• @tanstack/react-query — Data fetching and caching (requires a QueryClientProvider in your app)