npm package: @peoplecues/commons
Description: A reusable React component library for xto10x SaaS tools.
Author: xto10x
Latest version: 1.4.4

## @peoplecues/commons

A React component library built with Vite, Storybook, and styled-components. This library provides a wide range of UI components, theming utilities, and icon sets for rapid application development.

---

## ⚠️ Important: styled-components Instance

This library **exports its own instance of `styled-components`** (including `styled`, `ThemeProvider`, `createGlobalStyle`, and `keyframes`).

> **To avoid issues with multiple styled-components instances (which can break theming, context, and style injection), the consuming application should NOT install or use its own version of styled-components.**

Always use the exports from this library for all styled-components needs.

---

## Modal Exports

This library also exports modal utilities from [`styled-react-modal`]:

- `StyledReactModal` (default export from styled-react-modal)
- `ModalProvider`

These are available as named exports from the main entry point:

```js
import { StyledReactModal, ModalProvider } from "@peoplecues/commons";
```

---

## Entry Points

Entry points are defined in [`vite.config.js`](./vite.config.js) under `build.lib.entry` and mapped in [`package.json`](./package.json) > `exports`.

### Current Entry Points

- **index**: All named exports for all components/utilities.
  - Usage: `import { Button, ThemeProvider, ... } from '@peoplecues/commons';`
- **IconLib**: Import icons individually.
  - Usage: `import { warningFilled } from '@peoplecues/commons/IconLib';`
- **BulkSelector**: Import BulkSelector directly.
  - Usage: `import BulkSelector from '@peoplecues/commons/BulkSelector';`
- **DateTimePicker**: Import DateTimePicker directly.
  - Usage: `import DateTimePicker from '@peoplecues/commons/DateTimePicker';`

#### Adding New Entry Points

- Add the entry in `vite.config.js > build.lib.entry`.
- Add the corresponding path in `package.json > exports`.
- **Document the new entry point here in the README.**

---

## Local Development & Testing in Other Apps (using yalc)

1. Make your changes in this repo.
2. Run the build:
   ```sh
   yarn build
   ```
3. Publish to yalc:
   ```sh
   yalc publish
   ```

### In the consuming repo:

4. Add the package from yalc:
   ```sh
   yalc add @peoplecues/commons
   # (If a previous version exists, run `yarn remove @peoplecues/commons` first, or use `yalc update @peoplecues/commons`)
   ```
5. Install dependencies:
   ```sh
   yarn
   # or
   npm install
   ```
6. Start the app:
   ```sh
   yarn start
   # or
   npm run dev
   ```

---

## Storybook Usage

- **To run Storybook locally:**
  ```sh
  yarn storybook
  ```
- Some stories (e.g., **Avatar**) may not display anything by default. Use the controls panel to provide values and see the component render.

---

## Component Story Format (CSF3)

- The library has migrated to **CSF3** for Storybook stories.
- We **no longer use knobs, actions, etc.** from previous Storybook versions.

---

## File Extension Best Practices

- **Always use `.jsx` for files containing JSX.**
- This ensures proper syntax highlighting, linting, and build compatibility. Also might break otherwise.

---

## Summary of Key Exports

- All components and utilities as named exports from the main entry point
- Icon library and select components as separate entry points

---

For any new entry points or major changes, **update this README accordingly** and ensure the relevant paths are added to both `vite.config.js` and `package.json > exports`.

---

## Publishing to npm

### To publish as **beta**:

0. run
   ```sh
   yarn build
   ```
1. Set the version in `package.json` with a beta tag, e.g.:
   - `"version": "1.2.0-beta.0"`
   - Increment as needed: `1.2.0-beta.1`, `1.2.0-beta.2`, etc.
2. Login to npm (requires credentials and OTP sent to apps@xto10x mail):
   ```sh
   npm login
   ```
   To check if you are already logged in:
   ```sh
   npm whoami
   ```
3. Publish with the beta tag:
   ```sh
   yarn npm publish --tag beta
   ```
4. To use the beta version in another repo(can mention beta version too):
   ```sh
   npm install peoplecues/commons@beta
   ```

### To publish as **latest** (for stable or beta versions):

0. run
   ```sh
   yarn build
   ```
1. Set the version in `package.json` as a stable version, e.g.:
   - `"version": "1.2.0"`
2. Login to npm:
   ```sh
   npm login
   ```
   To check if you are already logged in:
   ```sh
   npm whoami
   ```
3. Publish as latest:
   ```sh
   npm publish
   ```
4. To remove any previous beta tag:
   ```sh
   npm dist-tag rm peoplecues/commons beta
   ```