# AGENTS.md — components-base

> React Native base components — cross-platform foundation (Web, iOS, Android).

## Package

`@telus-uds/components-base` — ~75 components in `src/`, each in its own folder. Verify the exact count with `ls packages/components-base/src/ | grep -E '^[A-Z]'` — this number changes as components are added or split.

## Component pattern

See [`.claude/rules/package-source.instructions.md`](../../.claude/rules/package-source.instructions.md) for the canonical pattern.

**Mandatory in every component**: `React.forwardRef`, `useThemeTokens`, `displayName`, named export (no default), `PropTypes`.

## File structure

```
src/
  MyComponent/
    MyComponent.jsx           # default (cross-platform) implementation
    MyComponent.native.jsx    # React Native-only override (loaded on iOS/Android via Metro resolver)
    SubPart.native.jsx        # platform-specific sub-component when behaviour diverges
    index.js                  # re-export: export { MyComponent } from './MyComponent'
  index.js                    # all named exports, alphabetical
  server.js                   # server-safe exports (no React Native)
```

Use `.native.jsx` (or `.native.js` for utilities) only when the cross-platform `MyComponent.jsx` cannot serve both web and native — e.g. when the component needs to call into React Native primitives that don't exist on web, or vice versa. The Metro bundler resolves `.native.*` first on iOS/Android; the web build ignores them. Real examples: `Checkbox/CheckboxInput.native.jsx`, `ActivityIndicator/Dots.native.jsx`, `Fieldset/FieldsetContainer.native.jsx`.

## Exports

- `src/index.js` — Named exports only, **no default exports**
- New components must be added to `src/index.js` in alphabetical order

## Testing

- Renderer: `@testing-library/react-native` (NOT `@testing-library/react`)
- **Always wrap in `<Theme>`**: `import { Theme } from '../../__fixtures__/Theme'`
- `vitest-fail-on-console` active — `console.error` fails tests (`console.warn` currently allowed); avoid both
- No jest-axe in this package (web-only)
- Runs against real React Native JS via vitest-native (platform ios); host elements render as `RCTView`/`RCTText`

## Vitest project

```bash
pnpm exec vitest run --project components-base
```

## Formatting

See root [`.prettierrc.cjs`](../../.prettierrc.cjs) and run `pnpm run lint:fix`.

## Lint

See root [`.eslintrc.cjs`](../../.eslintrc.cjs).