# Producteca UI Kit ⚛️⚡

> 📚 Documentation: [apps.producteca.com/producteca-ui-kit](https://apps.producteca.com/producteca-ui-kit)

## Features

- 🔹 [Node 22](https://nodejs.org/)
- ⚛️ [React 18](https://reactjs.org/)
- 📚 [Storybook 10](https://storybook.js.org/) - Components preview
- ⏩ [Vite](https://vitejs.dev/) - Run and build the project blazingly fast!
- 🔧 [Babel](https://babeljs.io/) - JavaScript transpilation for maximum browser compatibility
- ⚡  [Vitest](https://vitest.dev/) - Components Unit Testing
- 📐 [ESLint](https://eslint.org/) & [Prettier](https://prettier.io/) - Formatting and Linting
- 🌟 [Typescript](https://www.typescriptlang.org/)
- 🐶 [Husky](https://typicode.github.io/husky) & [Lint Staged](https://www.npmjs.com/package/lint-staged) - Pre-commit Hooks
- 👷 [Github Actions](https://github.com/features/actions)
- 🚀 [Semantic Release](https://semantic-release.gitbook.io/semantic-release) para automatizar el versionado y publicación de paquetes.

## Main Scripts

| Script | Command | Description |
|--------|---------|-------------|
| `dev` | `storybook dev -p 6006` | Starts Storybook in development mode on port 6006 |
| `build` | `rm -rf dist && tsc && vite build && babel dist ...` | Removes the `dist` folder, compiles TypeScript, builds the library using Vite, and transpiles with Babel for maximum browser compatibility |
| `build:storybook` | `storybook build` | Builds the static Storybook project |
| `build-storybook` | `storybook build` | Alias for `build:storybook` |
| `deploy` | `make deploy` | Deploys the project using the specified Makefile configuration |
| `lint` | `node linterteca-lint` | Runs linterteca to lint files with `.js` and `.jsx` extensions |
| `prettier` | `prettier --write "src/**/*.{ts,tsx,js,mdx}"` | Formats files in the `src` folder using Prettier |
| `test` | `vitest` | Runs tests using Vitest in watch mode |
| `test:cov` | `vitest run --coverage` | Executes tests and generates a coverage report |
| `prepare` | `husky` | Prepares the repository by installing Husky for Git hooks |
| `pre-commit` | `husky && husky install` | Installs Husky and sets up Git hooks for pre-commit validation |

## Storybook MCP

This library's Storybook exposes an [MCP](https://storybook.js.org/docs/ai/mcp/overview)
server so AI agents can query component docs and run interaction tests.

### Use it locally

```bash
bun run dev          # serves Storybook + MCP at http://localhost:6006/mcp
```

Register it with your agent (project scope):

```bash
npx mcp-add --type http --url "http://localhost:6006/mcp" --scope project
```

Claude Code users: the repo's `.mcp.json` already registers it — just run
`bun run dev`.

### Use the published server (Chromatic)

Each Chromatic build publishes the MCP at the `/mcp` route of the published
Storybook:

```
https://<branch>--<appId>.chromatic.com/mcp
```

Verify with: ask your agent to run `list-all-documentation`.

### Consuming it from other repos

To wire this MCP into other repos that depend on the UI kit — using the
Chromatic-published endpoint, user vs. project scope, OAuth, and troubleshooting
— see **[docs/mcp-setup.md](./docs/mcp-setup.md)**.

## 🌐 Browser Compatibility

Este proyecto utiliza **Babel** para transpilar el código JavaScript/TypeScript, garantizando compatibilidad con:

- **Navegadores modernos**: Chrome, Firefox, Safari, Edge (últimas 2 versiones)
- **Navegadores legacy**: Internet Explorer 11+
- **Dispositivos móviles**: iOS Safari, Chrome Mobile, Samsung Internet
- **Cobertura global**: >0.25% de usuarios, excluyendo navegadores obsoletos

La configuración de Babel incluye:
- `@babel/preset-env` para transpilación automática según el target
- `@babel/preset-react` para sintaxis JSX
- `@babel/preset-typescript` para TypeScript
- Plugins adicionales para características modernas de JavaScript

### Setting up `@producteca/producteca-ui-kit`

Follow these steps to integrate and configure the `@producteca/producteca-ui-kit` package in your project:

1. **Install the package**  
   Make sure to install the latest version of the package:

   ```bash
   bun install @producteca/producteca-ui-kit

   ```

2. **Import the styles**  
   Add the following line to your `app/css/setup.js` file:

   ```bash
   import "@producteca/producteca-ui-kit/dist/style.css";

   ```

3. **Remove old component instances**
   For any component that has been moved to the UI kit (like SelectField, CheckboxInput, etc.), you need to:

   - Remove the old component files from your project. For example:

     ```bash
     app/components/form/selectField
     app/components/form/checkboxInput
     # or any other component that has been moved to the UI kit
     ```

   - Update your imports to use the components from the UI kit:
     ```typescript
     import { SelectField, CheckboxInput /* other components */ } from '@producteca/producteca-ui-kit'
     ```

4. **Configure the locale (optional)**
   The kit ships in Spanish by default. To render it in another language, call `configureLocale` **once, during your app bootstrap**, before rendering any component:

   ```typescript
   import { configureLocale } from '@producteca/producteca-ui-kit'

   configureLocale('en')
   ```

   Supported locales: `'es'` (default), `'pt-BR'` and `'en'`.

   This single call covers the kit's own strings, the day and month names of both date pickers, and the internal labels of the MUI pickers.

   **The locale is read at render time and is not reactive.** Calling `configureLocale` after components have mounted will not update them — it is meant for bootstrap, not for a runtime language switcher. Keys that are missing from a non-Spanish bundle fall back to Spanish rather than showing the raw key.

## 📦 Publishing a New Version

Package publishing is now handled automatically via a GitHub Action triggered on `push` to the `main` or `master` branches.

You can also trigger it manually from the **Actions** tab using the `Release` workflow.

The workflow supports prerelease versions (e.g., `alpha`, `beta`) through the `prereleaseTag` input.

### 🚀 Manual Run (ONLY for prereleases)

1. Go to [Actions](https://github.com/Parsimotion/courierteca/actions).
2. Select the `Release` workflow.
3. Click `Run workflow`.
4. Enter the desired tag (e.g., `beta`) or leave as `alpha` (default).

> 🔐 The release process uses the contents of the `lib/` directory generated during build.

### ✅ Commit Linting with Husky

This project uses Commitlint along with Husky to ensure that all commit messages follow the [Conventional Commit format](https://www.conventionalcommits.org/en/v1.0.0/).

#### Why?

The conventional commit format allows you to:

- Automatically generate changelogs.
- Classify changes into versions (patch, minor, major).
- Maintain a clearer and more structured commit history.

#### 🛠️ Installation and Setup

Everything is already configured in the project. If you're working locally, make sure to run the following after cloning and installing dependencies:

```bash
npm install
npx husky install
```

This ensures that Git hooks are properly installed.

#### ⚙️ Relevant Files

- `.husky/commit-msg`: hook that runs commitlint before making a commit.
- `commitlint.config.js`: defines the rules that commit messages must follow.
- `.husky/pre-commit`: (optional) can run linters or other automated checks.

📝 Example of a valid commit message

```sh
feat: add primary button component
fix(ci): fix release configuration on test branch
chore(deps): update development dependencies
```

## 🧹 Branch Name Linter

This project uses [`linterteca`](https://www.npmjs.com/package/linterteca) to enforce consistent branch naming conventions across all development work.

The linter is automatically run as a `pre-push` Git hook using [Husky](https://typicode.github.io/husky/#/). To ensure the linter works properly:

#### ✅ Setup Instructions

1. Install all dependencies:

```bash
npm install
```

2. That's it! The linter will now run **automatically before each push** and will block invalid branch names.

#### 📛 Branch name rules

Allowed prefixes:

- `feature/`
- `fix/`
- `hotfix/`
- `release/`
- `docs/`
- `fix/`
- `refactor/`
- `chore/`
- `ci/`
- `test/`
- `perf`
- `style`
- `build/`.

If your branch name does not follow the required format, the push will be blocked with a helpful error message.

#### 🛠️ Bypass (not recommended)

To bypass the linter in exceptional cases:

```bash
git push --no-verify
```  

> Only use `--no-verify` if absolutely necessary and with team consensus.