npm package: @marwes-ui/react
Description: React adapter for Marwes core recipes.
Latest version: 0.0.4

# @marwes-ui/react

React adapter for Marwes core recipes.

## Responsibilities
- Provide React components and provider APIs.
- Resolve theme from context and call core recipes.
- Apply typed RenderKit output to React elements.

## Non-Responsibilities
- No component logic duplication from core.
- No preset CSS ownership.

## Install
```bash
pnpm add @marwes-ui/core @marwes-ui/react @marwes-ui/presets
```

## Quick Start
```tsx
import { MarwesProvider, Button, ButtonVariant, Input, Checkbox } from "@marwes-ui/react";
import { firstEdition } from "@marwes-ui/presets";
import "@marwes-ui/presets/firstEdition/styles.css";

export function App() {
  return (
    <MarwesProvider preset={firstEdition} theme={{ color: { primary: "#5B8CFF" } }}>
      <Button variant={ButtonVariant.primary}>Save</Button>
      <Input placeholder="Email" onValueChange={(v) => console.log(v)} />
      <Checkbox ariaLabel="Subscribe" />
    </MarwesProvider>
  );
}
```

## Button Philosophy

Marwes buttons follow a **semantic-first** approach:

### Recommended: Semantic Components
```tsx
import { CancelButton, SubmitButton, CreateButton, DangerButton } from "@marwes-ui/react";

// These auto-set AI-friendly action metadata
<CancelButton onClick={handleCancel}>Cancel</CancelButton>
<SubmitButton>Save</SubmitButton>
<CreateButton onClick={handleCreate}>New Item</CreateButton>
<DangerButton onClick={handleDelete}>Delete</DangerButton>
```

### Advanced: Raw Props with Type-Safe Enums
```tsx
import { Button, ButtonVariant, ButtonSize, ButtonAction } from "@marwes-ui/react";

// For dynamic or custom scenarios
<Button
  variant={ButtonVariant.primary}
  size={ButtonSize.md}
  action={ButtonAction.submit}
>
  Submit
</Button>
```

Semantic components are preferred for guaranteed AI context and consistent UX.

## Current Exports
Provider and hooks:
- `MarwesProvider`
- `useTheme`
- `useSystem`

Atoms:
- `Button`, `PrimaryButton`, `SecondaryButton`, `TextButton`
- `CancelButton`, `SubmitButton`, `CreateButton`, `DangerButton`, `LinkButton`
- `Input`
- `Icon`
- `Checkbox`
- `H1`, `H2`, `H3`
- `Paragraph`

Enums (const objects):
- `ButtonVariant` - `primary`, `secondary`, `text`
- `ButtonSize` - `xs`, `sm`, `md`, `lg`
- `ButtonAction` - `submit`, `cancel`, `create`, `delete`, `navigate`, `edit`, `reset`, `button`

Molecules:
- `CheckboxField`

Utilities:
- `useRenderKitDebug`

## Adapter Rules
- Treat `@marwes-ui/core` as source of truth for behavior and a11y.
- Apply RenderKit fields explicitly.
- Keep component wrappers thin and predictable.
- Do not hardcode Figma design values in adapters.

## Package Structure
- `src/provider/*` - provider + hooks
- `src/components/*` - React wrappers around core recipes
- `src/index.ts` - public exports

## Figma Mapping
If design changes originate in Figma, align token/state mapping with:
- `../../docs/FIGMA_TO_MARWES.md`

Most Figma changes should land in core theme/recipes and presets CSS first, then flow into React automatically.

## Scripts
- `pnpm --filter @marwes-ui/react dev`
- `pnpm --filter @marwes-ui/react build`
- `pnpm --filter @marwes-ui/react typecheck`

## Package Structure

```
dist/              # Build output (npm published files)
├── index.js       # ESM bundle
├── index.d.ts     # TypeScript declarations
└── index.js.map   # Source maps

src/               # Source files (not published)
├── components/    # React components
├── hooks/         # React hooks
└── provider/      # Context provider

tsconfig.json      # TypeScript config (noEmit: true)
tsup.config.ts     # Build configuration
```

**Important**: The `dist/` folder is generated by `pnpm build` and should never be edited directly. Only the `dist/` folder is published to npm (configured in `package.json` `files` field).

## Related Docs
- `../../docs/PROJECT.md`
- `../../docs/ARCHITECTURE.md`
- `../../docs/ENGINEERING.md`