@validationcloud/fractal-ui

Validation Cloud's shared React component library with design tokens and Tailwind CSS utilities.

Install

npm install @validationcloud/fractal-ui react react-dom tailwindcss

Setup

Import components:

import { Button } from '@validationcloud/fractal-ui';

Add styles to your global stylesheet (requires Tailwind 4):

@import 'tailwindcss';
@import '@validationcloud/fractal-ui/tailwind.css';

ECharts Maps

The package bundles GeoJSON maps (world, continents, regions, and per-continent breakdowns) and lazy-loads them automatically when you use EChartsRenderer with type: 'map'. Import map utilities from @validationcloud/fractal-ui/charts. Install echarts as a peer dependency.

A machine-readable catalog of all available maps, their descriptions, and region names is published at @validationcloud/fractal-ui/maps.json. From non-JS environments you can fetch it directly from unpkg:

curl -L https://unpkg.com/@validationcloud/fractal-ui/dist/maps.json

Adding A New Map

To add another generated map to this package:

1. Add a new MapDefinition entry in scripts/generate-maps.ts with a fileName, description, and buildRegions implementation.
2. Update src/components/echarts-renderer/register-map.ts so the new map name points at its generated GeoJSON file.
3. Update src/components/echarts-renderer/natural-earth-projection.ts if the new map needs world-style projection handling or custom Lambert parameters.
4. Run pnpm generate:maps to regenerate the GeoJSON assets, map centers, map styles, and src/maps.json.
5. Add or update a Storybook example so the new map can be verified visually.

Development

Requires Node.js 22.14.0+ and pnpm.

pnpm install
pnpm storybook

Open http://localhost:6006

Live docs: https://fractal-ui.vercel.app/

Tech Stack

• React 19
• TypeScript 5
• Tailwind CSS 4
• Radix UI (headless primitives)
• Zod (schema validation)
• Vite (build tooling)
• Storybook (component documentation)
• Vitest (testing)
• ESLint + Prettier (code quality)
• pnpm (package manager)