1Money Component UI

This repository contains the source for @1money/component-ui, a React component library used across 1Money front-end projects.

It combines reusable UI components with a 1Money SCSS design system, Storybook for local development, and dual CommonJS/ES module builds for distribution.

Live Storybook

Browse the published component documentation and interactive examples at:

https://1money-co.github.io/1money-components-ui/**

The site is built from the main branch (pnpm build:demo) and deployed to GitHub Pages on every push. For unreleased work on other branches, run Storybook locally with pnpm dev.

Releases

Include a new stable package.json version in a PR to main. PR Release Version checks the version before merge; Auto Tag creates the matching annotated tag and GitHub Release after merge. The tag starts the existing NPM CICD workflow. Repository tooling and documentation alone do not require a release; published MCP server changes do.

See Automatic release tags for the required GitHub App setup, manual prereleases, dry runs, and recovery. pnpm release prepares a version locally; npm publication runs through GitHub Actions.

Features

• React and TypeScript component library
• Reusable UI building blocks styled for 1Money products
• SCSS design system in src/styles/
• Storybook development server on port 6205
• Dual build output to lib/ and es/

Installation

Requires React 19 (react and react-dom >=19.0.0). Components take ref as a regular prop and use useId, so React 18 and earlier are not supported.

Install the package and the required React dependencies:

pnpm add @1money/component-ui react react-dom primereact primeicons

Then import the library stylesheet once in your app entrypoint:

import '@1money/component-ui/index.css';

Quick Start

Named imports are available from the root package entry:

import {
  Button,
  Checkbox,
  CheckboxGroup,
  Grid,
  Icons,
  notification,
  Tag,
  Tooltip,
} from '@1money/component-ui';
import '@1money/component-ui/index.css';

export function Example() {
  return (
    <>
      <Grid gutter={[16, 16]}>
        <Grid.Col span={12} md={6}>
          <Button color="primary">Continue</Button>
        </Grid.Col>
        <Grid.Col span={12} md={6}>
          <Checkbox label="Accept terms" />
        </Grid.Col>
        <Grid.Col span={12} md={6}>
          <CheckboxGroup
            options={['Email', 'SMS']}
            defaultValue={['Email']}
          />
        </Grid.Col>
      </Grid>

      <Tag label="Active" color="success" />

      <button id="help-trigger" type="button">
        <Icons name="info" />
      </button>
      <Tooltip anchorSelect="#help-trigger" body="More details" />

      {/*
        notification is a static API. Call it from event handlers,
        effects, or other client-side actions.
      */}
      <Button
        onClick={() =>
          notification.success({
            title: 'Saved',
            body: 'Settings were updated.',
          })
        }
      >
        Show notification
      </Button>
    </>
  );
}

Tree-shakeable subpath imports are also supported:

import { Button } from '@1money/component-ui/Button';
import { Spinner } from '@1money/component-ui/Spinner';

Components In This Repository

The current source tree includes these component modules:

• Accordion
• Alert
• Button
• Calendar
• Carousel
• Cell
• Checkbox (+ CheckboxGroup)
• CoachMark
• Copy (+ Clipboard)
• Dialog
• Divider
• Drawer
• Dropdown
• Empty
• Flex
• Grid (+ Row, Col)
• Icons (+ IconWrapper, IconHover)
• Input
• Link
• Navigation (+ Nav, NavigationStepper)
• notification (static Notification API)
• Pagination
• Popconfirm
• Portal
• ProForm
• Progress
• Radio (+ RadioGroup)
• ResizeObserver
• Segment
• Select
• Skeleton
• Slider
• Space
• Spinner
• Step
• Switch
• Table (+ VirtualTable)
• Tabs
• Tag
• Tooltip
• Tour
• Trigger
• Typography
• Upload (+ UploadFileBar)
• VirtualList

The package manifest defines subpath exports for top-level component modules. Grouped exports such as Row, Col, Nav, and VirtualTable are imported from their parent module subpaths.

Styling

Consumers should import @1money/component-ui/index.css.

When building or updating components inside this repository, SCSS files should import the internal style API:

@use '@/styles/api' as theme;

The style system follows a layered boundary model:

• theme/ = design-domain API
• system/ = sx engine
• recipes/ = library recipe helpers
• public/ = consumer-facing facade exported by src/styles/_api.scss

Component SCSS should not import system/* or tokens/* directly. theme/functions is reserved for rare library-only reader access such as om-line-height(...) or om-line-height-px(...). The design token and utility system is documented in src/styles/README.md.

Development

Install dependencies:

pnpm install

Start Storybook locally:

pnpm dev

Storybook runs at http://localhost:6205.

Useful commands:

pnpm test
pnpm lint
pnpm build
pnpm new
pnpm new Button -f

Build output is generated in:

• lib/ for CommonJS
• es/ for ES modules

Required i18n for feature changes

Every new feature or enhancement must deliver its i18n in the same PR. Cover all library-owned copy, including validation, empty/loading states, tooltips, and accessibility labels. Feature flags and gray releases do not waive this requirement.

• Maintain the locale contract in src/locale/interface.ts and translations in all supported packs: src/locale/en_US/, src/locale/zh_CN/, src/locale/pt_BR/, and src/locale/es_ES/. Keep required keys and placeholders aligned.
• Use the existing ConfigProvider locale APIs for defaults and formatting; preserve caller prop overrides, English fallback, and runtime language changes.
• Review each changed file for i18n, verify all three languages in Storybook, and include check results in the PR. Explain an N/A claim when there is no user-facing copy or locale-sensitive behavior. Missing translations block feature completion and merge.

See the contributor rules and ConfigProvider usage for details.

Project Structure

src/
├── components/   # Component source
├── styles/       # SCSS public/theme/system/recipes/internal layers
└── index.ts      # Root library exports

Release Notes

• Package name: @1money/component-ui
• Repository: https://github.com/1Money-Co/1money-components-ui
• License: MIT