LCT Africa UI Library

This repository contains the internal UI component library for LCT Africa. It is built with React, TypeScript and Vite and is intended to provide reusable, tested, and consistently styled UI components for LCT Africa frontend projects.

Quickstart

Prerequisites

• Node.js v18+ (recommended)
• npm

Install dependencies

npm install

Development

• Storybook (recommended for developing components in isolation):

npm run storybook

Build (production)

npm run build

Testing

• Run tests (watch mode):

npm run test

• Run tests once (CI):

npm run test:no-watch

Linting & Typecheck

npm run lint
npm run typecheck

Release / Publish

The release script builds the package and publishes to the configured npm registry. Ensure the package version is updated before publishing.

npm run release

Project layout

Typical files and folders:

src/
  index.ts            # library entry (re-exports public API from components)
  styles.css          # exported global styles
  components/
    ui/               # all components live here, each colocated with stories/tests
      button/
        Button.tsx
        index.ts       # barrel export for the component (re-exports public API)
        Button.stories.tsx
        Button.test.tsx
vitest.setup.ts       # test setup for vitest
vite.config.ts        # build + dts + test config
tsconfig.app.json

Build output

• The built package is emitted to dist/ and includes:
  • index.js (ES module)
  • index.d.ts (types)
  • index.css (compiled CSS exported as styles.css)

Module exports are configured in package.json so consumers can import the package as @lctafrica/ui and the stylesheet as @lctafrica/ui/styles.css.

Conventions & patterns

• Components are colocated with their stories and tests under src/components/ui/.

• Stories: Storybook is the canonical environment for browsing and developing components in isolation.

• Tests: Vitest + Testing Library are used for unit/interaction tests. vitest.setup.ts configures globals and test environment.

• Styling: Tailwind CSS is used along with utility helpers (e.g., class-variance-authority, tailwind-merge). Import the package stylesheet in consumers to get base styles.

• Accessibility: We use Radix primitives for some components; follow Radix guidance (e.g., provide DialogTitle / Dialog.Description when using DialogContent).

• Types: Type declarations are produced and emitted to dist/ by the build pipeline.

• Component folder convention: each component lives in its own folder and includes the implementation, a component-level index.ts that re-exports the component's public API (barrel export), a story (*.stories.*) and tests (*.test.*). Example:

src/components/ui/button/
  Button.tsx
  index.ts         # re-exports `Button` and related types
  Button.stories.tsx
  Button.test.tsx

• Barrel export pattern: every component provides a small index.ts (barrel) that re-exports its public symbols. The library root src/index.ts then re-exports all components and utilities, creating a single public surface. This allows consumers to import from @lctafrica/ui:

import { Button } from "@lctafrica/ui";

• All public exports are unified at src/index.ts so consumers do not need to import deep paths.

Naming conventions

• Component folder names: kebab-case. Example: my-button/, date-picker/.

• Component, story and test filenames: PascalCase. Example:

src/components/ui/my-button/
  MyButton.tsx
  MyButton.stories.tsx
  MyButton.test.tsx
  index.ts

• Utility files (helpers, formatters, small libraries) should be kebab-case filenames. Example:

src/lib/format-date.ts
src/lib/validate-url.ts

• Component names: PascalCase and implemented as React functional components using the function keyword (not const with arrow functions). Example:

// src/components/ui/my-button/MyButton.tsx
export function MyButton(props: MyButtonProps) {
  return <button {...props}>Click</button>;
}

• Exports: components must use named exports (the export keyword). Do not use default exports. Example barrel index.ts for the component:

// src/components/ui/my-button/index.ts
export { MyButton } from "./MyButton";
export type { MyButtonProps } from "./MyButton";

• Utility constants: use ALL_CAPS with underscores. Example:

export const API_TIMEOUT_MS = 5000;

• Rationale: these conventions improve discoverability, consistent import paths, and make automated refactors and code generation simpler.

Scripts (available)

• build — tsc -b && vite build — build JS, CSS and types
• lint — run ESLint across the codebase
• test — vitest (watch by default)
• test:no-watch — vitest run (single run, for CI)
• storybook — start Storybook (dev)
• build-storybook — build Storybook static site
• prepare — husky (installs Git hooks)
• release — builds and publishes the package
• typecheck — tsc -b --noEmit (strict type checking)

How to consume

Install the package as a dependency in your app (internal registry or from npm if published):

npm install @lctafrica/ui

Then import components and styles in your application:

import React from "react";
import { Button } from "@lctafrica/ui";
import "@lctafrica/ui/styles.css";

export default function App() {
  return <Button>Click me</Button>;
}

Note: react and react-dom are peer dependencies and must be provided by the consumer (React 18+).

CI / Recommended checks

Typical CI steps:

npm ci
npm run lint
npm run typecheck
npm run test:no-watch
npm run build

Developer tooling

• Formatting: prettier (configured via lint-staged)
• Linting: eslint with TypeScript and React rules
• Pre-commit: Husky + lint-staged run formatting and ESLint fixes on staged files

Troubleshooting & notes

• If you see Radix warnings like "DialogContent requires a DialogTitle", add a DialogTitle or wrap it with a visually-hidden title to meet accessibility requirements.
• This repo does not ship React itself — make sure the consuming app provides react/react-dom matching the peer dependency range.

Contributing

1. Clone the repo and create a feature branch from dev branch: git checkout -b feature/your-feature
2. Add tests and stories for UI work
3. Run npm run lint, npm run typecheck, and npm run test before opening a PR

This library is intended for internal use within LCT Africa projects.