npm package: @reditui/kit
Description: UI components and utilities for REditUI - NumberInput, OutputNumberLabel, and number utilities
Latest version: 0.1.2

# @reditui/kit

UI components and utilities for REditUI (レヂツイ) - React components for number input with locale support.

## Installation

```bash
npm install @reditui/kit @chakra-ui/react react
```

## Components

### NumberInput

Business number input component with comprehensive validation and formatting.

**Note on Error Messages:** Error messages are displayed in Japanese as this package is designed for REditUI (レヂツイ) users who are primarily Japanese speakers. If you need internationalization support, you can use the `onValidationError` callback to implement custom error handling.

**Features:**
- Internal draft state during input
- Commit only on blur
- Normalization and validation on blur
- Support for fractionDigits, min/max
- Right-aligned display for numbers
- Locale-aware number parsing and formatting
- Customizable error handling

**Example:**

```tsx
import { NumberInput } from '@reditui/kit';
import { useState } from 'react';

function App() {
  const [value, setValue] = useState<number | null>(null);
  const [error, setError] = useState<string | null>(null);

  return (
    <NumberInput
      value={value}
      onCommit={setValue}
      onValidationError={setError}
      fractionDigits={2}
      min={0}
      max={1000000}
      locale="en-US"
      placeholder="Enter amount"
    />
  );
}
```

**Props:**

| Prop | Type | Description |
|------|------|-------------|
| `value` | `number \| null` | Current value |
| `onCommit` | `(value: number \| null) => void` | Callback when value is committed (on blur) |
| `fractionDigits` | `number` | Maximum decimal places (optional) |
| `min` | `number` | Minimum allowed value (optional) |
| `max` | `number` | Maximum allowed value (optional) |
| `locale` | `string` | Locale for number formatting (e.g., 'en-US', 'ja-JP') (optional) |
| `onValidationError` | `(error: string \| null) => void` | Callback when validation error occurs (optional) |

Plus all standard Chakra UI Input props.

### OutputNumberLabel

Read-only number display component with locale-aware formatting.

**Features:**
- Locale-aware number formatting with grouping separators
- Support for fractionDigits to control decimal places
- Optional prefix and suffix (e.g., currency symbols, units)
- Prefix and suffix are hidden when value is null
- No user interaction (read-only display)

**Example:**

```tsx
import { OutputNumberLabel } from '@reditui/kit';

function App() {
  return (
    <>
      {/* Display currency */}
      <OutputNumberLabel 
        value={1234.56} 
        fractionDigits={2} 
        locale="en-US" 
        prefix="$" 
      />
      {/* Output: $1,234.56 */}

      {/* Display with suffix */}
      <OutputNumberLabel 
        value={100} 
        fractionDigits={0} 
        locale="ja-JP" 
        suffix="個" 
      />
      {/* Output: 100個 */}

      {/* Display with both prefix and suffix */}
      <OutputNumberLabel 
        value={1234.56} 
        fractionDigits={2} 
        locale="en-US" 
        prefix="$" 
        suffix=" USD" 
      />
      {/* Output: $1,234.56 USD */}
    </>
  );
}
```

**Props:**

| Prop | Type | Description |
|------|------|-------------|
| `value` | `number \| null` | Current value |
| `fractionDigits` | `number` | Maximum decimal places for formatting (default: 0) |
| `prefix` | `string` | Prefix string to prepend (hidden when value is null) (optional) |
| `suffix` | `string` | Suffix string to append (hidden when value is null) (optional) |
| `locale` | `string` | Locale for number formatting (e.g., 'en-US', 'ja-JP') (optional) |

Plus all standard Chakra UI Text props.

## Utilities

The package also exports useful number utility functions:

### getLocaleSeparators

Get locale-specific number format separators.

```tsx
import { getLocaleSeparators } from '@reditui/kit';

const { decimal, group } = getLocaleSeparators('en-US');
// { decimal: '.', group: ',' }

const { decimal, group } = getLocaleSeparators('de-DE');
// { decimal: ',', group: '.' }
```

### normalizeInput

Normalize input string for validation with locale-aware parsing.

```tsx
import { normalizeInput } from '@reditui/kit';

normalizeInput('1,234.56', 'en-US'); // '1234.56'
normalizeInput('1.234,56', 'de-DE'); // '1234.56'
normalizeInput('  １２３  ', 'ja-JP'); // '123' (full-width to half-width)
```

### formatNumber

Format number for display using Intl.NumberFormat with locale support.

```tsx
import { formatNumber } from '@reditui/kit';

formatNumber(1234.56, 2, 'en-US'); // '1,234.56'
formatNumber(1234.56, 2, 'de-DE'); // '1.234,56'
formatNumber(1234.56, 2, 'ja-JP'); // '1,234.56'
```

### formatNumberWithAffixes

Format number with optional prefix and suffix for display.

```tsx
import { formatNumberWithAffixes } from '@reditui/kit';

formatNumberWithAffixes(1234.56, 2, 'en-US', '$', ' USD'); // '$1,234.56 USD'
formatNumberWithAffixes(100, 0, 'ja-JP', '¥'); // '¥100'
formatNumberWithAffixes(null, 2, 'en-US', '$', ' USD'); // '' (empty string)
```

### toHalfWidth

Convert full-width characters to half-width.

```tsx
import { toHalfWidth } from '@reditui/kit';

toHalfWidth('１２３'); // '123'
toHalfWidth('−５。５'); // '-5.5'
```

### normalizeLocaleNumber

Normalize locale-specific number input to standard format for parsing.

```tsx
import { normalizeLocaleNumber } from '@reditui/kit';

normalizeLocaleNumber('1,234.56', 'en-US'); // '1234.56'
normalizeLocaleNumber('1.234,56', 'de-DE'); // '1234.56'
```

## Requirements

- React 18.0.0 or higher (or React 19.0.0)
- Chakra UI v3.25.0 or higher
- Node.js 18.0.0 or higher

## License

MIT

## Publishing to npm

This package is published to npm registry as a scoped package `@reditui/kit`.

**📖 詳細な日本語ガイド**: [PUBLISHING.md](./PUBLISHING.md) をご覧ください

### Prerequisites

1. npm account with publish permissions for `@reditui` scope
2. `NPM_TOKEN` secret configured in GitHub repository settings

### Publishing Process

The package is automatically published to npm when a new tag is pushed:

```bash
# Update version in packages/kit/package.json first
cd packages/kit
npm version patch  # or minor, major

# Create and push a git tag
git tag kit-v0.1.1
git push origin kit-v0.1.1
```

The GitHub Actions workflow `.github/workflows/publish-kit.yml` will automatically:
1. Build the package
2. Publish to npm registry with provenance

### Manual Publishing (if needed)

```bash
cd packages/kit
npm run build
npm publish --access public
```

Note: Make sure you're logged in with `npm login` first.