npm package: @ikame-lib/pcl
Description: A modern component library built with Vite, Tailwind CSS, and shadcn/ui
Author: Peih Brown
Latest version: 0.2.10

# @ikame-lib/pcl — React Component Library

A modern React component library built with Vite, Tailwind CSS, shadcn/ui (Radix), and TypeScript.

- ⚡ Vite • ⚛️ React 18 • 🎨 Tailwind CSS • 🧩 Radix/shadcn • 📦 TypeScript

## What you get

- Accessible, composable UI primitives (Radix-based)
- Theming via CSS custom properties (light/dark ready)
- Tree-shakeable named exports with TypeScript types
- Single compiled stylesheet you can drop into any app

---

## Use in another project

Peer dependencies: react >= 18, react-dom >= 18

### 1) Install

```bash
npm install @ikame-lib/pcl
# or
pnpm add @ikame-lib/pcl
# or
yarn add @ikame-lib/pcl
```

### 2) Import styles once

You must include the library CSS one time in your app (entry file or layout):

```ts
// Vite/CRA entry (e.g., src/main.tsx)
import '@ikame-lib/pcl/styles'
```

```ts
// Next.js App Router (e.g., app/layout.tsx)
import '@ikame-lib/pcl/styles'
```

### 3) Use components

```tsx
import { Button, Card, CardHeader, CardTitle, CardContent } from '@ikame-lib/pcl'

export default function Example() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Hello</CardTitle>
      </CardHeader>
      <CardContent>
        <Button variant="primary">Click me</Button>
      </CardContent>
    </Card>
  )
}
```

Notes for Next.js:
- Components that use client-side interactivity should be placed in files with the `"use client"` directive.
- Import the CSS in your root layout or a top-level client component once.

### Override theme (optional)

Override CSS variables to customize the theme:

```css
/* In your app's global CSS */
:root {
  --primary: 19 90% 55%;
  --primary-foreground: 0 0% 100%;
  /* See src/styles/globals.css for the full token list */
}

.dark {
  --primary: 19 91% 66%;
}
```

---

## Develop this library

Requirements:
- Node.js 18+
- npm (or pnpm/yarn)

### 1) Clone and install

```bash
git clone https://gitlab.ikameglobal.com/hiepdh/ilego.git
cd ilego
npm install
```

### 2) Run the demo/docs locally

```bash
npm run dev
```

This starts a local docs playground (see `src/components/docs/Demo.tsx`).

### 3) Project structure (important)

- UI components: `src/components/ui/`
- Demo pages: `src/components/docs/demos/`
- Demo sidebar list: `src/components/docs/components-list.ts`
- Library exports: `src/index.ts`
- Global styles and tokens: `src/styles/globals.css`

### 4) Add a new component

1. Create the UI component in `src/components/ui/YourComponent.tsx`.
   - Export named component(s), prefer `forwardRef` for interactive elements (works with Radix triggers).
   - Keep public API small and typed. Follow naming conventions (PascalCase component names).
2. Export it from `src/index.ts` (and export its prop type via `ComponentProps<typeof YourComponent>` if needed).
3. Add a demo in `src/components/docs/demos/your-component-demo.tsx` and export it from `src/components/docs/demos/index.ts`.
4. Register the component in `src/components/docs/components-list.ts` so it appears in the docs sidebar.
5. Run `npm run dev` and verify the demo looks and behaves correctly.

### 5) Edit an existing component

- Update the file in `src/components/ui/`.
- If you change its API, update demos and `src/index.ts` exports/types accordingly.
- Keep changes small; ensure no linter errors.

### 6) Remove a component

1. Remove its demo from `src/components/docs/demos/` and update `demos/index.ts`.
2. Remove it from `src/components/docs/components-list.ts`.
3. Remove export(s) from `src/index.ts`.
4. Delete the UI file under `src/components/ui/`.

### 7) Lint, build, preview

```bash
npm run lint
npm run build
npm run preview
```

Outputs:
- `dist/index.js` (ESM)
- `dist/index.umd.cjs` (UMD)
- `dist/index.d.ts` (types)
- `dist/style.css` (compiled styles)

---

## Release & publish

We publish the scoped package `@ikame-lib/pcl` as public.

1) Bump version (Semantic Versioning):

```bash
# patch:   0.1.3 -> 0.1.4
npm version patch
# minor:   0.1.3 -> 0.2.0
npm version minor
# major:   0.1.3 -> 1.0.0
npm version major
```

2) Build and verify publish contents:

```bash
npm run build
npm pack --dry-run
```

3) Login and publish to npm:

```bash
npm login
npm publish --access public
```

4) Push to Git with tags and changelog:

```bash
git add .
git commit -m "chore(release): vX.Y.Z"
git tag vX.Y.Z
git push origin HEAD --tags
```

See `publish-guide.md` for screenshots and more details.

---

## Troubleshooting

- Styles not applied: ensure you imported `@ikame-lib/pcl/styles` once at app entry or layout.
- Next.js interactivity: put `"use client"` at the top of files that render interactive components.
- Dropdown menu doesn’t open: if you wrap triggers with `asChild`, the child must forward refs. Our `Button` already does.
- Ring/outline color unexpected: make sure your app doesn’t override the CSS variables used by the library.

---

## License

MIT — see `LICENSE` if present.