bx-ui-components

Reusable BX React components for Next.js applications.

This package owns the shared UI, shared styles, and the small set of text strings used inside those shared components. Apps should use this package for shared UI only. Each app still manages its own page content, translations, authentication, data fetching, and business logic.

What Is Inside

• src/ui: reusable UI primitives and compound components.
• src/styles/styles.css: package CSS output source.
• locales/<locale>/common-components-strings.json: source of truth for shared component strings.
• src/i18n/locales.ts: static import map that loads the locale folder files into the package.
• tailwind.preset.cjs: optional Tailwind preset for consuming apps.
• tsdown.config.ts: package build configuration.
• .storybook: local documentation and visual testing setup.

Component Inventory

| Area | Components | Source | | --- | --- | --- | | Core UI | Button | src/ui/button | | Core UI | Input | src/ui/input | | Core UI | Textarea | src/ui/textarea | | Core UI | Label | src/ui/label | | Core UI | Checkbox | src/ui/checkbox | | Core UI | Switch | src/ui/switch | | Core UI | RadioGroup, RadioGroupItem, RadioGroupCircleItem, RadioGroupCheckItem | src/ui/radio-group | | Core UI | RadioButtonCard | src/ui/radioButtonCard | | Forms | Form, FormField, FormItem, FormLabel, FormControl, FormDescription, FormMessage | src/ui/form | | Forms | MultiLingualSupportInputs | src/ui/MultiLingualInputs | | Selection | Select, SelectTrigger, SelectValue, SelectContent, SelectItem, SelectItems, SelectInput | src/ui/select | | Selection | MVPSelect and related command select parts | src/ui/SelectCommand | | Selection | MultiSelect | src/ui/multi-select | | Selection | CustomSelect | src/ui/custom-select | | Selection | Command and related command parts | src/ui/command | | Date | CalendarBase | src/ui/calendar | | Date | DateCalendar | src/ui/DateCalendar | | Date | DateField | src/ui/DateField | | Date | DateRangePicker | src/ui/DateRangePicker | | Date | DateOfBirthSelector | src/ui/DateOfBirthSelector | | Date | DobCalendar, YearsAndMonthsDropdown | src/ui/DobCalendar | | Layout / Overlay | Accordion and related parts | src/ui/accordion | | Layout / Overlay | Alert, AlertTitle, AlertDescription | src/ui/alert | | Layout / Overlay | AlertDialog and related parts | src/ui/alert-dialog | | Layout / Overlay | Dialog and related parts | src/ui/dialog | | Layout / Overlay | DropdownMenu and related parts | src/ui/dropdown-menu | | Layout / Overlay | HoverCard, HoverCardContent, StandardHoverCardContent | src/ui/hover-card | | Layout / Overlay | NavigationMenu and related parts | src/ui/navigation-menu | | Layout / Overlay | Popover, PopoverTrigger, PopoverContent | src/ui/popover | | Layout / Overlay | ScrollArea, ScrollBar | src/ui/scroll-area | | Layout / Overlay | Separator | src/ui/separator | | Layout / Overlay | Sheet and related parts | src/ui/sheet | | Layout / Overlay | Sidebar and related parts | src/ui/sidebar | | Layout / Overlay | Tabs, TabsList, TabsTrigger, TabsContent | src/ui/tabs | | Layout / Overlay | Tooltip, TooltipTrigger, TooltipContent, TooltipProvider | src/ui/tooltip | | Data Display | BaseTable | src/ui/base-table | | Data Display | Table, TableHeader, TableBody, TableFooter, TableHead, TableRow, TableCell, TableCaption | src/ui/table | | Data Display | Badge | src/ui/badge | | Data Display | Avatar, AvatarImage, AvatarFallback | src/ui/avatar | | Data Display | Card, CardHeader, CardFooter, CardTitle, CardDescription, CardContent | src/ui/card | | Data Display | Text | src/ui/text | | Data Display | MainHeader, SubHeader, Header, CardLabel, CardValue, TextTag | src/ui/TextTags | | Data Display | SortingArrows | src/ui/SortingArrows | | Data Display | SlashIcon | src/ui/SlashIcon | | Charts / Editor | BarChart, tooltipLabelFormatter | src/ui/bar-chart | | Charts / Editor | VerticalBarChart | src/ui/vertical-bar-chart | | Charts / Editor | ChartContainer, ChartTooltipContent, ChartLegendContent | src/ui/chart | | Charts / Editor | TipTapEditor | src/ui/TiptapEditor | | Charts / Editor | TipTapToolbar and related toolbar parts | src/ui/TipTapToolbar | | Charts / Editor | TipTap extensions | src/ui/TiptapExtensions | | App-Backed UI | RouteChangeAlertPopUp | src/ui/RouteChangeAlertPopUp | | App-Backed UI | GetScrollTypesAlert | src/ui/GetScrollAlert | | Context | RadioGroupContext | src/ui/RadioGroupContext |

Translation Flow

Common component strings do not depend on the consuming app's getStaticProps, serverSideTranslations, auth setup, or internet connection.

The flow is:

1. A component calls useCommonComponentStrings().
2. The hook reads the locale from the URL path by finding the first path segment that matches a supported locale folder.
3. It looks up that locale from the bundled locale data imported by src/i18n/locales.ts.
4. If the exact locale is missing, it tries a broader match and then falls back to en.
5. The component renders plain translated text.

Examples:

/ca-fr/sample -> ca-fr
/marketing/ca-fr/sample -> ca-fr

This supports consuming apps that use a Next.js basePath, such as /marketing. The base path is ignored because it is not a locale folder.

Each locale folder contains only:

locales/<locale>/common-components-strings.json

The locales folder is the source of truth. Pathfinder translation tooling should create or update this file in each locale folder. Do not manually maintain a separate aggregate JSON file.

src/i18n/locales.ts is not the source of truth. It is only the static import map that lets React, Next.js, and tsup bundle the JSON files from locales. The browser cannot directly scan or load files from node_modules/bx-ui-components/locales, so each locale JSON file must be imported somewhere in the package. That is why locales.ts exists.

This keeps bx-ui-components independent from consuming apps:

• no bx-fe getStaticProps,
• no bx-fe serverSideTranslations,
• no runtime translation fetch,
• no copying locale files into the app public folder.

When a new locale folder is added, also add it to src/i18n/locales.ts so it is included in the built package.

Do not add app namespaces like common.json, bx_v1.json, or course.find_course.json back into this package. Those belong to applications, not the component library.

Add Or Update Strings

When a component needs text:

1. Add a stable component key, for example baseTable.prev.
2. Add that key to every locales/<locale>/common-components-strings.json file through the Pathfinder translation UI/script.
3. If a new locale folder was added, add its import and map entry in src/i18n/locales.ts.
4. Use it from the component:

import { useCommonComponentStrings } from "src/i18n/useCommonComponentStrings";

const t = useCommonComponentStrings();

return <button>{t("baseTable.prev")}</button>;

Use component-owned key names like select.noData, routeChange.leavePage, or textEditor.heading1. Avoid old app namespace keys like bx_v1:cm_prev.

Local Development

Install dependencies:

npm install

Run Storybook:

npm run storybook

Run type checking:

npm run typecheck

Build the package:

npm run build

Create a local package tarball:

npm run pack:local

This creates a package file like:

bx-ui-components-0.1.0.tgz

Test In bx-fe Locally

From bx-ui-components:

npm run build
npm run pack:local

From the consuming app, for example bx-fe:

npm install ../bx-ui-components/bx-ui-components-0.1.0.tgz
npm run dev

Then open a locale route such as:

http://localhost:2000/ca-fr/sample

If the browser still shows stale labels from an older package build, stop the dev server, remove the app's .next folder, restart, and hard refresh the browser.

Use In A New Project

Install the package:

npm install bx-ui-components

Import CSS once in the app entry point:

import "bx-ui-components/styles.css";

Use components:

import { BaseTable, Button, Input } from "bx-ui-components";

For Tailwind, include the package output in the app content list:

module.exports = {
  presets: [require("bx-ui-components/tailwind.preset.cjs")],
  content: [
    "./pages/**/*.{ts,tsx}",
    "./src/**/*.{ts,tsx}",
    "./node_modules/bx-ui-components/dist/**/*.{js,cjs,mjs}"
  ]
};

Publish

Before publishing:

npm run typecheck
npm run build
npm run build-storybook

Then publish:

npm login
npm version patch
npm publish

Use npm publish --access public only if the npm package is scoped and public access is required.

Storybook

Storybook is the main local documentation surface. It includes:

• grouped stories covering all shared UI components,
• shared component catalog,
• translation flow documentation,
• sample BaseTable usage with pagination,
• mocked examples for app-backed components such as discount code inputs and the rich text editor.

Run:

npm run storybook

Build static Storybook docs:

npm run build-storybook