@lctafrica/ui 1.1.4 → 1.1.5

package/README.md

@@ -1,141 +1,228 @@
 # LCT Africa UI Library
 
-## This is an internal UI component library for **LCT Africa**, built with **React**, **TypeScript**, and **Vite**. It provides reusable, consistent, and tested UI components for use across LCT Africa’s frontend projects.
+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.
 
-## Project Structure
+## Quickstart
 
-```
-src/
-  components/
-    ui/
-      button/
-        Button.tsx
-        Button.stories.tsx
-        Button.test.tsx
-```
-
----
-
-## Getting Started
-
-### Prerequisites
+Prerequisites
 
 - Node.js v18+ (recommended)
-- npm or yarn
+- npm
 
-### Installation
+Install dependencies
 
 ```bash
 npm install
-# or
-yarn install
 ```
 
-### Development
+Development
 
-Start the development server with hot module replacement:
+- Storybook (recommended for developing components in isolation):
 
 ```bash
-npm run dev
-# or
-yarn dev
+npm run storybook
 ```
 
----
-
-## Building for Production
+Build (production)
 
 ```bash
 npm run build
-# or
-yarn build
 ```
 
----
+Testing
+
+- Run tests (watch mode):
+
+```bash
+npm run test
+```
 
-## Linting
+- Run tests once (CI):
 
-This project uses **ESLint** with recommended **TypeScript** and **React** rules.
+```bash
+npm run test:no-watch
+```
 
-You can expand the ESLint configuration for type-aware or React-specific lint rules. For example:
+Linting & Typecheck
 
 ```bash
-npm install --save-dev eslint-plugin-react-x eslint-plugin-react-dom
+npm run lint
+npm run typecheck
 ```
 
-Check `eslint.config.js` for comments on stricter or stylistic rules.
+Release / Publish
 
----
+The `release` script builds the package and publishes to the configured npm registry. Ensure the package `version` is updated before publishing.
+
+```bash
+npm run release
+```
 
-## Testing
+## Project layout
 
-Example tests are located alongside components, e.g.:
+Typical files and folders:
 
 ```
-src/components/ui/button/Button.test.tsx
+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
 ```
 
-Run tests with:
+Build output
 
-```bash
-npm run test
-# or
-yarn test
+- 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`:
+
+```ts
+import { Button } from "@lctafrica/ui";
+```
+
+- All public exports are unified at `src/index.ts` so consumers do not need to import deep paths.
 
-## Storybook
+### Naming conventions
 
-Component stories are located in:
+- Component folder names: kebab-case. Example: `my-button/`, `date-picker/`.
+
+- Component, story and test filenames: PascalCase. Example:
 
 ```
-src/components/ui/button/Button.stories.tsx
+src/components/ui/my-button/
+  MyButton.tsx
+  MyButton.stories.tsx
+  MyButton.test.tsx
+  index.ts
 ```
 
-Run Storybook:
+- Utility files (helpers, formatters, small libraries) should be kebab-case filenames. Example:
 
-```bash
-npm run storybook
-# or
-yarn storybook
+```
+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:
 
-## Project Highlights
+```tsx
+// src/components/ui/my-button/MyButton.tsx
+export function MyButton(props: MyButtonProps) {
+  return <button {...props}>Click</button>;
+}
+```
 
-- **React + TypeScript:** Modern, type-safe UI development
-- **Vite:** Fast build and dev server
-- **Component-driven:** UI components organized under `ui`
-- **Testing:** Example tests using Vitest
-- **ESLint:** Ensures code quality and consistency
+- Exports: components must use named exports (the `export` keyword). Do not use default exports. Example barrel `index.ts` for the component:
 
----
+```ts
+// src/components/ui/my-button/index.ts
+export { MyButton } from "./MyButton";
+export type { MyButtonProps } from "./MyButton";
+```
 
-## Contributing
+- Utility constants: use ALL_CAPS with underscores. Example:
 
-1. Fork the repository
-2. Create your feature branch:
+```ts
+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):
 
 ```bash
-git checkout -b feature/YourFeature
+npm install @lctafrica/ui
 ```
 
-3. Commit your changes:
+Then import components and styles in your application:
 
-```bash
-git commit -am "Add some feature"
+```tsx
+import React from "react";
+import { Button } from "@lctafrica/ui";
+import "@lctafrica/ui/styles.css";
+
+export default function App() {
+  return <Button>Click me</Button>;
+}
 ```
 
-4. Push to your branch:
+Note: `react` and `react-dom` are peer dependencies and must be provided by the consumer (React 18+).
+
+## CI / Recommended checks
+
+Typical CI steps:
 
 ```bash
-git push origin feature/YourFeature
+npm ci
+npm run lint
+npm run typecheck
+npm run test:no-watch
+npm run build
 ```
 
-5. Open a pull request
+## 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
 
-> **Note:** This library is intended for internal use within LCT Africa projects only.
+This library is intended for internal use within LCT Africa projects.
 
 ---