# Contributing

> Set up the repo, run the example app on web, iOS and Android, and follow the project structure and conventions.

The repo is a pnpm monorepo: the library in `packages/ui/`, an Expo example app in `apps/example/` that renders against the library source (edits hot-reload), and this docs site in `apps/docs/`.

The component pages and their prop playgrounds are listed once, in `apps/docs/src/catalog/` (`catalog.constants.ts` and `playgrounds.tsx`): the docs sidebar, each page's playground and the example app's drawer all read it. Whole screens built from the components are in the examples gallery, `examples/`. A new component or prop control goes there.

## Setup

```sh
git clone https://github.com/patine-ui/patine.git
cd react-native-pickers
pnpm install   # also installs the git hooks
```

## Scripts

| Command | What it does |
|---|---|
| `pnpm web` | Example app in the browser |
| `pnpm ios` | Example app in the iOS Simulator |
| `pnpm android` | Example app in the Android emulator |
| `pnpm docs` | This site at `localhost:3001` |
| `pnpm test` | Jest + React Native Testing Library |
| `pnpm lint` | Biome: lint, format and import order |
| `pnpm format` | Fix whatever lint can fix |
| `pnpm typecheck` | TypeScript, including tests |
| `pnpm build` | Compile to `lib/` (ESM + `.d.ts`) |
| `pnpm gen:emoji` | Regenerate the emoji data from emojibase |
| `pnpm gen:countries` | Regenerate the country data |
| `pnpm gen:timezones` | Regenerate the time zone data |

## Project structure

`packages/ui/src/` is grouped by category (`core`, `foundations`, `actions`, `inputs`, `pickers`, `overlays`), with one folder per component family inside. Each is published as a flat subpath, `patine-ui/<folder>`. They build on `overlays/sheet` (bottom sheets) and `core` (theme, shared hooks and utils). Imports only flow one way: feature → `sheet` → `core`.

Every folder has the same layout:

```
src/select/
├─ Select.tsx        components render only
├─ components/             smaller render-only parts
├─ hooks/                  state and event handling
├─ select.utils.ts         pure logic
├─ select.utils.test.ts    unit tests for every util
├─ select.types.ts
├─ select.constants.ts
├─ select.styles.ts
├─ Select.test.tsx   interaction tests
└─ index.ts                the folder's public API
```

Where new code goes:

- **Pure logic** (calculations, filtering, date math) goes in `<feature>.utils.ts`, with a unit test next to it.
- **State and event handling** goes in a hook under `hooks/`.
- **Components** only render: they call hooks and utils, with no inline logic.
- **Types, constants and styles** go in their own `<feature>.*.ts` files, never inside components.

## Conventions

- Tests sit next to the file they test.
- Use arrow functions: `export const fn = () =>`, not `export function`.
- Returned objects with two or more properties go one property per line. A Biome plugin enforces it, and `pnpm format` fixes it.
- Imports come in three blocks separated by a blank line: React and React Native, other packages, then our own code.
- Commit messages follow [Conventional Commits](https://www.conventionalcommits.org): `feat:`, `fix:`, `refactor(select):`, `docs:` and so on.

## Checks

The pre-commit hook formats and lints the staged files and runs typecheck, and the commit-msg hook checks the message. On every pull request, CI runs lint, typecheck, tests and the build. Pull requests are squash-merged, so CI also checks that the PR title is a Conventional Commit: it becomes the commit message on `master`.

## Releasing

Releases are automated with [release-please](https://github.com/googleapis/release-please) and driven by the commit messages on `master`:

- `fix:` makes a patch release, `feat:` a minor one, and a `!` or a `BREAKING CHANGE:` footer a major one (a minor one before 1.0).
- Only commits that touch `packages/ui/` trigger a release.
- After every merge, release-please updates a `chore(release): vX.Y.Z` pull request with the version bump and the [changelog](/changelog) entry. Nothing ships while it stays open.
- Merging that PR tags the version, creates the GitHub release, publishes to npm and redeploys these docs.
- To pick the version yourself, add a `Release-As: 1.0.0` footer to a commit.

The docs are versioned from the git tags: `/docs` always matches the latest release on npm, `master` is published as **Next** at `/docs/next`, and every minor line keeps its own version in the dropdown.
