Road to v1: Introducing @thesis-co/cent-react

packages/cent-react/COPYRIGHT

@@ -0,0 +1,3 @@
+Copyright (c) 2026 Thesis, Inc.
+
+All rights reserved.

packages/cent-react/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thesis, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/cent-react/README.md

@@ -0,0 +1,241 @@
+# @thesis-co/cent-react
+
+React bindings for [@thesis-co/cent](https://www.npmjs.com/package/@thesis-co/cent) - display, input, and manage money values with ease.
+
+## Installation
+
+```bash
+npm install @thesis-co/cent @thesis-co/cent-react
+```
+
+## Quick Start
+
+### Display Money
+
+```tsx
+import { MoneyDisplay } from '@thesis-co/cent-react';
+import { Money } from '@thesis-co/cent';
+
+// Basic usage
+<MoneyDisplay value={Money("$1234.56")} />
+// → "$1,234.56"
+
+// Compact notation
+<MoneyDisplay value={Money("$1500000")} compact />
+// → "$1.5M"
+
+// Crypto with satoshis
+<MoneyDisplay value={Money("0.001 BTC")} preferredUnit="sat" />
+// → "100,000 sats"
+
+// Locale formatting
+<MoneyDisplay value={Money("€1234.56")} locale="de-DE" />
+// → "1.234,56 €"
+
+// Null handling with placeholder
+<MoneyDisplay value={null} placeholder="—" />
+// → "—"
+```
+
+### Custom Parts Rendering
+
+```tsx
+<MoneyDisplay value={Money("$99.99")}>
+  {({ parts, isNegative }) => (
+    <span className={isNegative ? 'text-red-500' : ''}>
+      {parts.map((part, i) => (
+        <span key={i} className={part.type}>
+          {part.value}
+        </span>
+      ))}
+    </span>
+  )}
+</MoneyDisplay>
+```
+
+### Money Input
+
+```tsx
+import { MoneyInput } from '@thesis-co/cent-react';
+import { Money } from '@thesis-co/cent';
+
+function PaymentForm() {
+  const [amount, setAmount] = useState<Money | null>(null);
+
+  return (
+    <MoneyInput
+      name="amount"
+      value={amount}
+      onChange={(e) => setAmount(e.target.value)}
+      currency="USD"
+      min="$1"
+      max="$10000"
+      placeholder="Enter amount"
+    />
+  );
+}
+```
+
+### With react-hook-form
+
+```tsx
+import { Controller, useForm } from 'react-hook-form';
+import { MoneyInput } from '@thesis-co/cent-react';
+
+function CheckoutForm() {
+  const { control, handleSubmit } = useForm();
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <Controller
+        name="amount"
+        control={control}
+        render={({ field }) => (
+          <MoneyInput {...field} currency="USD" />
+        )}
+      />
+    </form>
+  );
+}
+```
+
+### useMoney Hook
+
+```tsx
+import { useMoney, MoneyDisplay } from '@thesis-co/cent-react';
+
+function TipCalculator() {
+  const bill = useMoney({ currency: 'USD' });
+  const tip = bill.money?.multiply(0.18) ?? null;
+
+  return (
+    <div>
+      <input {...bill.inputProps} placeholder="Bill amount" />
+      {bill.error && <span className="error">{bill.error.message}</span>}
+
+      <p>Tip (18%): <MoneyDisplay value={tip} /></p>
+      <p>Total: <MoneyDisplay value={bill.money?.add(tip ?? Money.zero('USD'))} /></p>
+    </div>
+  );
+}
+```
+
+### MoneyProvider
+
+Set default configuration for all descendant components:
+
+```tsx
+import { MoneyProvider } from '@thesis-co/cent-react';
+
+function App() {
+  return (
+    <MoneyProvider locale="de-DE" defaultCurrency="EUR">
+      <YourApp />
+    </MoneyProvider>
+  );
+}
+```
+
+### useExchangeRate Hook
+
+```tsx
+import { useExchangeRate, MoneyDisplay } from '@thesis-co/cent-react';
+import { Money } from '@thesis-co/cent';
+
+function CurrencyConverter() {
+  const [usd, setUsd] = useState(Money.zero('USD'));
+
+  const { convert, isLoading, isStale, refetch } = useExchangeRate({
+    from: 'USD',
+    to: 'EUR',
+    pollInterval: 60000, // Refresh every minute
+    staleThreshold: 300000, // Stale after 5 minutes
+  });
+
+  const eur = convert(usd);
+
+  return (
+    <div>
+      <MoneyInput value={usd} onChange={(e) => setUsd(e.target.value)} currency="USD" />
+
+      {isLoading ? (
+        <span>Loading...</span>
+      ) : (
+        <MoneyDisplay value={eur} />
+      )}
+
+      {isStale && (
+        <button onClick={refetch}>Rate may be outdated. Refresh?</button>
+      )}
+    </div>
+  );
+}
+```
+
+**Note:** `useExchangeRate` requires an `exchangeRateResolver` to be provided via `MoneyProvider`:
+
+```tsx
+<MoneyProvider
+  exchangeRateResolver={async (from, to) => {
+    const response = await fetch(`/api/rates/${from}/${to}`);
+    const data = await response.json();
+    return new ExchangeRate(from, to, data.rate);
+  }}
+>
+  <App />
+</MoneyProvider>
+```
+
+### MoneyDiff
+
+Display the difference between two money values:
+
+```tsx
+import { MoneyDiff } from '@thesis-co/cent-react';
+import { Money } from '@thesis-co/cent';
+
+// Basic difference
+<MoneyDiff value={Money("$120")} compareTo={Money("$100")} />
+// → "+$20.00"
+
+// With percentage change
+<MoneyDiff
+  value={Money("$120")}
+  compareTo={Money("$100")}
+  showPercentage
+/>
+// → "+$20.00 (+20.00%)"
+
+// Custom rendering
+<MoneyDiff value={newPrice} compareTo={oldPrice}>
+  {({ direction, formatted }) => (
+    <span className={direction === 'increase' ? 'text-green-500' : 'text-red-500'}>
+      {formatted.difference}
+    </span>
+  )}
+</MoneyDiff>
+```
+
+## API Reference
+
+### Components
+
+| Component | Description |
+|-----------|-------------|
+| `MoneyDisplay` | Display formatted money values |
+| `MoneyInput` | Controlled input for money values |
+| `MoneyDiff` | Display difference between two values |
+| `MoneyProvider` | Context provider for default configuration |
+
+### Hooks
+
+| Hook | Description |
+|------|-------------|
+| `useMoney` | Manage money state with validation |
+| `useExchangeRate` | Fetch and manage exchange rates |
+| `useMoneyConfig` | Access MoneyProvider context |
+
+## Requirements
+
+- React 17.0.0 or later
+- @thesis-co/cent 0.0.5 or later

packages/cent-react/jest.config.js

@@ -0,0 +1,15 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'jsdom',
+  testMatch: ['**/test/**/*.test.ts', '**/test/**/*.test.tsx'],
+  setupFilesAfterEnv: ['<rootDir>/test/setup.ts'],
+  transform: {
+    '^.+\\.tsx?$': [
+      'ts-jest',
+      {
+        tsconfig: './tsconfig.json',
+      },
+    ],
+  },
+}

packages/cent-react/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@thesis-co/cent-react",
+  "version": "0.0.1",
+  "description": "React bindings for @thesis-co/cent - display, input, and manage money values",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thesis/cent.git",
+    "directory": "packages/cent-react"
+  },
+  "keywords": [
+    "react",
+    "money",
+    "currency",
+    "finance",
+    "input",
+    "form",
+    "cents"
+  ],
+  "author": "Matt Luongo (@mhluongo)",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "lint": "pnpx @biomejs/biome check",
+    "lint:fix": "pnpx @biomejs/biome check --write",
+    "build": "tsc",
+    "test": "jest",
+    "prepublishOnly": "pnpm run build && pnpm run test && pnpm run lint"
+  },
+  "devDependencies": {
+    "@thesis-co/cent": "workspace:*",
+    "@testing-library/jest-dom": "^6.4.0",
+    "@testing-library/react": "^14.2.0",
+    "@testing-library/user-event": "^14.5.0",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.11.24",
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "ts-jest": "^29.1.2"
+  },
+  "peerDependencies": {
+    "@thesis-co/cent": ">=0.0.5",
+    "react": ">=17.0.0"
+  }
+}