@paygreen/pgui

Core UI components library for Paygreen applications built with React and Chakra UI.

📦 Installation

Base Installation

# Install the core library
npm install @paygreen/pgui

# Install required peer dependencies
npm install react react-dom @chakra-ui/react @emotion/react @emotion/styled

Component-Specific Dependencies

Install additional packages based on the components you want to use:

| Component | Required Package | Command | |-----------|------------------|---------| | DatePicker | @internationalized/date | npm install @internationalized/date | | Select | react-select | npm install react-select | | InputPhone | react-phone-number-input | npm install react-phone-number-input | | InputMask | use-mask-input | npm install use-mask-input | | DataTable | @tanstack/react-table | npm install @tanstack/react-table | | All Icons | react-icons | npm install react-icons |

Complete Installation (All Components)

# Install everything at once
npm install @paygreen/pgui react react-dom @chakra-ui/react @emotion/react @emotion/styled @internationalized/date react-select react-phone-number-input use-mask-input @tanstack/react-table react-icons

🎨 CSS Setup

// In your main App.js or index.js
import '@paygreen/pgui/src/styles/index.css';

🚀 Basic Usage

import React from 'react';
import { ChakraProvider } from '@chakra-ui/react';
import { DatePicker, Select, Input, systemTheme } from '@paygreen/pgui';
import '@paygreen/pgui/src/styles/index.css';

function App() {
  return (
    <ChakraProvider value={systemTheme}>
      {/* Your components */}
    </ChakraProvider>
  );
}

🎞️ Animations

pgui exposes a curated set of named animationStyle presets so consumer apps stop hardcoding durations, easings and keyframes. Apps pick a semantic name; pgui owns the underlying values.

Available animationStyles

<Box animationStyle="slideInTop" />
<Box animationStyle={{ _open: 'slideInTop', _closed: 'slideOutTop' }} />

| Name | Composition | | --- | --- | | fadeIn | fade-in + fast + decelerate | | fadeOut | fade-out + fast + accelerate | | slideInTop / slideInBottom / slideInLeft / slideInRight | slide-from-X, fade-in + moderate + decelerate | | slideOutTop / slideOutBottom / slideOutLeft / slideOutRight | slide-to-X, fade-out + fast + accelerate |

Slide distances are Chakra's subtle 0.5rem variants. For panel-sized motion (drawers, full overlays), reach for Chakra's built-in slide-fade-in/out (placement-driven) directly.

Enter and exit are intentionally asymmetric: slideIn* runs at moderate (200ms) with decelerate so content settles in; slideOut* runs at fast (150ms) with accelerate so dismissals feel snappy. Fade follows the same enter-slower / exit-faster pacing.

Override animationDuration / animationTimingFunction at the call site if a specific case needs a different pacing:

<Box animationStyle="slideInTop" animationDuration="slow" />

Internal tokens

pgui consumes Chakra v3's default duration scale (fastest 50ms → slowest 500ms) as-is + one off-scale durations.spin (800ms) for continuous Spinner / Loader rotation, and adds 3 design-semantic easings (standard / accelerate / decelerate, Material-inspired) alongside Chakra's CSS-keyword easings. These tokens drive the animationStyle presets above and pgui-internal component transitions — they are not exposed as a JS bridge for consumer apps.

Convention

Any duration or easing in pgui or consumer apps should come from a pgui token rather than a hardcoded value (200ms, cubic-bezier(...)). Reviewed at PR time.

Enter + exit animations

For elements that mount/unmount based on state (dropdowns, error messages, overlays), use Chakra v3's <Presence> with conditional animationName. This keeps the element mounted during the exit animation, then unmounts on animationend. No JS animation lib required.

import { Presence } from '@chakra-ui/react';

<Presence
  present={open}
  animationName={{
    _open: 'slide-from-top, fade-in',
    _closed: 'slide-to-top, fade-out',
  }}
  animationDuration="moderate"
  animationTimingFunction="standard"
>
  {/* content */}
</Presence>

The slide-from-X / slide-to-X, fade-in / fade-out and scale-in / scale-out keyframes ship with Chakra v3 — combine them comma-separated for compound entry/exit.

Tokens consumed by pgui components

For reference when migrating an app: the components below already pull from the tokens above.

| Component | Tokens consumed | | --- | --- | | ActionsButton | durations.faster, easings.standard | | CardExpandable (card root) | durations.moderate | | CardExpandable (header hover) | durations.moderate | | CardExpandable (chevron) | durations.fast, easings.standard | | DataList (rows) | durations.moderate | | DataTable (row wrapper) | durations.moderate | | DatePicker (calendar enter/exit) | scale-fade-in / scale-fade-out via the Chakra v3 datePicker slot recipe defaults | | FieldWrapper (error message enter/exit) | <Presence> + slide-from-top, fade-in / slide-to-top, fade-out + durations.fast | | InputPhone (country dropdown enter/exit) | <Presence> + slide-from-top, fade-in / slide-to-top, fade-out + durations.moderate | | InputPhone (option list item) | durations.faster, easings.standard | | Loader | durations.spin | | Pagination (page text hover) | durations.moderate | | Sidebar (slide open/close) | durations.slow (configurable), easings.standard | | Sidebar (nav item hover) | durations.moderate, easings.standard |

See the Foundations / Animations story in Storybook for live previews.

🔧 Development & Testing

Why YALC?

YALC (Yet Another Local Cache) is the best tool for testing libraries locally because it:

• ✅ No symlinks - Avoids React duplicate issues from npm link
• ✅ Real package simulation - Works exactly like published packages
• ✅ Fast updates - Push changes instantly to consuming projects
• ✅ No conflicts - Prevents peer dependency resolution issues
• ✅ Production-like - Tests the actual built package, not source

Setting up YALC

1. Install YALC globally

npm install -g yalc

2. In this library (pgui/)

# Generate types if necessary 
npx @chakra-ui/cli typegen ./src/theme/index.ts

# Build and publish to local store
npm run build
yalc publish

# For development - rebuild and push changes
npm run build
yalc push  # Updates all projects using this package

3. In your test project

# Install from local YALC store
yalc add @paygreen/pgui
npm install

# When done testing, clean up
yalc remove @paygreen/pgui
npm install @paygreen/pgui  # Back to npm registry

Development Workflow

# 1. Make changes to components in pgui/
# 2. Build and push
npm run build && yalc push

# 3. Your test project automatically gets the updates
# 4. Test your changes

# 5. When ready, publish to npm
npm publish

Useful YALC Commands

# See which packages are published locally
yalc installations show

# Remove package from YALC store
yalc remove @paygreen/pgui --all

# Clean all YALC installations
yalc remove --all

🏗️ Building

# Build the library
npm run build

# Output files:
# - dist/index.mjs (ES modules)
# - dist/index.js (CommonJS)
# - dist/index.d.ts (TypeScript definitions)
# - dist/pgui.css (Compiled styles)

🐛 Troubleshooting

CSS Not Loading

Make sure you import the CSS file:

import '@paygreen/pgui/src/styles/index.css';

Missing Dependencies

If you get an error about missing packages, install the required dependency for the component you're using (see table above).

📋 Requirements

• React ^18.0.0 || ^19.0.0
• Node.js >= 16
• TypeScript >= 4.5 (if using TypeScript)

📄 License

Private - Paygreen Internal Use Only