nihonput 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hanab
+
+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.

package/README.ja.md

@@ -0,0 +1,318 @@
+<p align="center">
+  <img src="https://img.shields.io/npm/v/nihonput?style=flat-square" alt="npm version" />
+  <img src="https://img.shields.io/npm/l/nihonput?style=flat-square" alt="license" />
+  <img src="https://img.shields.io/badge/React-18%2B-61dafb?style=flat-square&logo=react" alt="React 18+" />
+  <img src="https://img.shields.io/badge/TypeScript-5.0%2B-3178c6?style=flat-square&logo=typescript" alt="TypeScript" />
+</p>
+
+<h1 align="center">nihonput</h1>
+
+<p align="center">
+  <strong>React用 日本語入力フォーム制御ライブラリ</strong>
+</p>
+
+<p align="center">
+  日本語フォーム入力を扱うためのHeadless React Hooksライブラリ。<br />
+  カタカナ、郵便番号、電話番号などの自動変換・バリデーション・フォーマットを提供します。
+</p>
+
+<p align="center">
+  <a href="./README.md">🇺🇸 English</a>
+</p>
+
+---
+
+## 特徴
+
+- **カタカナ / ひらがな** — 自動変換とバリデーション
+- **郵便番号** — `1234567` → `123-4567` へのフォーマットとバリデーション
+- **都道府県** — バリデーションと自動補完（例: `東京` → `東京都`）
+- **住所** — 全角/半角の文字幅制御
+- **電話番号** — ハイフン自動挿入とバリデーション
+- **IME対応** — 日本語IME変換中の適切なハンドリング
+- **Headless** — UIなし、ロジックのみ。どんなデザインシステムとも組み合わせ可能
+- **Tree-shaking対応** — 必要なものだけインポート可能
+
+---
+
+## インストール
+
+```bash
+npm install nihonput
+```
+
+```bash
+pnpm add nihonput
+```
+
+```bash
+yarn add nihonput
+```
+
+---
+
+## クイックスタート
+
+```tsx
+import { useNameField } from 'nihonput';
+
+function NameInput() {
+  const field = useNameField({
+    kanaMode: 'auto-convert',
+  });
+
+  return (
+    <input
+      value={field.value}
+      onChange={field.onChange}
+      onBlur={field.onBlur}
+      onCompositionStart={field.onCompositionStart}
+      onCompositionEnd={field.onCompositionEnd}
+      placeholder="フリガナ"
+    />
+  );
+}
+```
+
+`やまだ たろう` と入力 → blur時に自動で `ヤマダ タロウ` に変換されます。
+
+---
+
+## Hooks
+
+### useNameField
+
+フリガナなど、カタカナ入力用のフィールド。
+
+```tsx
+const field = useNameField({
+  kanaMode: 'auto-convert',      // または 'error-on-hiragana'
+  normalizeOn: 'blur',           // 'blur' | 'change' | 'compositionEnd'
+  validateOn: 'blur',            // 'blur' | 'change' | 'submit'
+  errorMessages: {
+    katakanaOnly: 'カタカナで入力してください',
+  },
+});
+```
+
+| オプション | 値 | 説明 |
+|-----------|-----|------|
+| `kanaMode` | `'auto-convert'` | ひらがな → カタカナ自動変換 |
+| | `'error-on-hiragana'` | ひらがな入力時にエラー表示 |
+| `normalizeOn` | `'blur'` `'change'` `'compositionEnd'` | 正規化のタイミング |
+| `validateOn` | `'blur'` `'change'` `'submit'` | バリデーションのタイミング |
+
+---
+
+### usePostalCodeField
+
+郵便番号フィールド用。
+
+```tsx
+const field = usePostalCodeField({
+  widthMode: 'half-width-only',  // または 'full-width-only'
+  onInvalid: 'auto-convert',     // または 'error'
+  autoHyphen: true,
+});
+```
+
+| オプション | 値 | 説明 |
+|-----------|-----|------|
+| `widthMode` | `'half-width-only'` | 半角のみ許可（`123-4567`） |
+| | `'full-width-only'` | 全角のみ許可（`１２３−４５６７`） |
+| `onInvalid` | `'auto-convert'` | 自動変換 |
+| | `'error'` | エラー表示 |
+| `autoHyphen` | `true` / `false` | ハイフン自動挿入 |
+
+**変換例:** `１２３４５６７` → `123-4567`
+
+---
+
+### usePrefectureField
+
+都道府県フィールド用。
+
+```tsx
+const field = usePrefectureField({
+  autoComplete: true,
+});
+```
+
+| オプション | 値 | 説明 |
+|-----------|-----|------|
+| `autoComplete` | `true` / `false` | 短縮名を自動補完 |
+
+**変換例:** `東京` → `東京都`、`大阪` → `大阪府`
+
+---
+
+### useAddressField
+
+住所フィールド用。文字幅の制御が可能。
+
+```tsx
+const field = useAddressField({
+  alphanumericMode: 'full-width-only',  // または 'allow-half-width'
+  onInvalid: 'auto-convert',
+});
+```
+
+| オプション | 値 | 説明 |
+|-----------|-----|------|
+| `alphanumericMode` | `'full-width-only'` | 半角英数字を全角に変換 |
+| | `'allow-half-width'` | 半角も許可 |
+| `onInvalid` | `'auto-convert'` / `'error'` | 違反時の動作 |
+
+**変換例:** `渋谷区1-2-3` → `渋谷区１−２−３`
+
+---
+
+### usePhoneNumberField
+
+電話番号フィールド用。
+
+```tsx
+const field = usePhoneNumberField({
+  onInvalid: 'auto-convert',
+  autoHyphen: true,
+});
+```
+
+| オプション | 値 | 説明 |
+|-----------|-----|------|
+| `onInvalid` | `'auto-convert'` / `'error'` | 違反時の動作 |
+| `autoHyphen` | `true` / `false` | ハイフン自動挿入 |
+
+**変換例:** `０９０１２３４５６７８` → `090-1234-5678`
+
+---
+
+## 戻り値
+
+すべてのフックは同じインターフェースを返します:
+
+```tsx
+interface FieldReturn {
+  value: string;                    // 現在の値
+  onChange: (e) => void;            // changeイベントハンドラ
+  onBlur: (e) => void;              // blurイベントハンドラ
+  onCompositionStart: (e) => void;  // IME変換開始
+  onCompositionEnd: (e) => void;    // IME変換確定
+  error: string | null;             // エラーメッセージ
+  isValidating: boolean;            // バリデーション中かどうか
+  isComposing: boolean;             // IME変換中かどうか
+}
+```
+
+---
+
+## 単体関数
+
+フックを使わずに、バリデーション関数や正規化関数を単体で使用できます。
+
+### バリデーション関数
+
+```tsx
+import {
+  validateKatakana,
+  validateHiragana,
+  validatePostalCode,
+  validatePrefecture,
+  validatePhoneNumber,
+} from 'nihonput';
+
+validateKatakana('カタカナ');       // true
+validateKatakana('ひらがな');       // false
+
+validatePostalCode('123-4567');    // true
+validatePostalCode('1234567');     // true
+
+validatePrefecture('東京都');       // true
+validatePrefecture('東京');         // true（短縮形もOK）
+
+validatePhoneNumber('090-1234-5678'); // true
+```
+
+### 正規化関数
+
+```tsx
+import {
+  toKatakana,
+  toHiragana,
+  toFullWidth,
+  toHalfWidth,
+  addPostalCodeHyphen,
+  addPhoneNumberHyphen,
+} from 'nihonput';
+
+toKatakana('ひらがな');              // 'ヒラガナ'
+toHiragana('カタカナ');              // 'かたかな'
+
+toFullWidth('abc123');              // 'ａｂｃ１２３'
+toHalfWidth('１２３');               // '123'
+
+addPostalCodeHyphen('1234567');     // '123-4567'
+addPhoneNumberHyphen('09012345678'); // '090-1234-5678'
+```
+
+---
+
+## React Hook Form との連携
+
+```tsx
+import { useForm } from 'react-hook-form';
+import { toKatakana, validateKatakana } from 'nihonput';
+
+function Form() {
+  const { register, handleSubmit, setValue, formState: { errors } } = useForm();
+
+  return (
+    <form onSubmit={handleSubmit(console.log)}>
+      <input
+        {...register('furigana', {
+          validate: (v) => validateKatakana(v) || 'カタカナで入力してください',
+        })}
+        onBlur={(e) => setValue('furigana', toKatakana(e.target.value))}
+      />
+      {errors.furigana && <span>{errors.furigana.message}</span>}
+
+      <button type="submit">送信</button>
+    </form>
+  );
+}
+```
+
+---
+
+## エクスポート一覧
+
+### Hooks
+- `useNameField`
+- `usePostalCodeField`
+- `usePrefectureField`
+- `useAddressField`
+- `usePhoneNumberField`
+
+### バリデーション関数
+- `validateKatakana` / `containsHiragana`
+- `validateHiragana` / `containsKatakana`
+- `validatePostalCode` / `isHalfWidthPostalCode` / `isFullWidthPostalCode`
+- `validatePrefecture` / `normalizePrefecture`
+- `validatePhoneNumber` / `isHalfWidthPhoneNumber`
+
+### 正規化関数
+- `toKatakana` / `toHiragana`
+- `toFullWidth` / `toHalfWidth`
+- `toFullWidthNumbers` / `toHalfWidthNumbers`
+- `addPostalCodeHyphen` / `addPhoneNumberHyphen`
+
+### 定数
+- `PREFECTURES` — 47都道府県の配列
+- `PREFECTURE_SHORT_NAMES` — 短縮名から正式名へのマップ
+- `defaultErrorMessages` — デフォルトエラーメッセージ
+
+---
+
+## ライセンス
+
+MIT © [Hanab Labs](https://github.com/HanabLabs)

package/README.md

@@ -0,0 +1,318 @@
+<p align="center">
+  <img src="https://img.shields.io/npm/v/nihonput?style=flat-square" alt="npm version" />
+  <img src="https://img.shields.io/npm/l/nihonput?style=flat-square" alt="license" />
+  <img src="https://img.shields.io/badge/React-18%2B-61dafb?style=flat-square&logo=react" alt="React 18+" />
+  <img src="https://img.shields.io/badge/TypeScript-5.0%2B-3178c6?style=flat-square&logo=typescript" alt="TypeScript" />
+</p>
+
+<h1 align="center">nihonput</h1>
+
+<p align="center">
+  <strong>Japanese Input Form Control Library for React</strong>
+</p>
+
+<p align="center">
+  A headless React hooks library for handling Japanese form inputs.<br />
+  Automatic conversion, validation, and formatting for Katakana, postal codes, phone numbers, and more.
+</p>
+
+<p align="center">
+  <a href="./README.ja.md">🇯🇵 日本語</a>
+</p>
+
+---
+
+## Features
+
+- **Katakana / Hiragana** — Auto-convert and validate Japanese kana
+- **Postal Code** — Format `1234567` → `123-4567` with validation
+- **Prefecture** — Validate and auto-complete (e.g., `東京` → `東京都`)
+- **Address** — Full-width / half-width character control
+- **Phone Number** — Format with hyphens and validate
+- **IME Aware** — Proper handling of Japanese IME composition
+- **Headless** — No UI, just logic. Use with any design system
+- **Tree-shakeable** — Import only what you need
+
+---
+
+## Installation
+
+```bash
+npm install nihonput
+```
+
+```bash
+pnpm add nihonput
+```
+
+```bash
+yarn add nihonput
+```
+
+---
+
+## Quick Start
+
+```tsx
+import { useNameField } from 'nihonput';
+
+function NameInput() {
+  const field = useNameField({
+    kanaMode: 'auto-convert',
+  });
+
+  return (
+    <input
+      value={field.value}
+      onChange={field.onChange}
+      onBlur={field.onBlur}
+      onCompositionStart={field.onCompositionStart}
+      onCompositionEnd={field.onCompositionEnd}
+      placeholder="フリガナ"
+    />
+  );
+}
+```
+
+Type `やまだ たろう` → automatically converts to `ヤマダ タロウ` on blur.
+
+---
+
+## Hooks
+
+### useNameField
+
+For name fields with Katakana input.
+
+```tsx
+const field = useNameField({
+  kanaMode: 'auto-convert',      // or 'error-on-hiragana'
+  normalizeOn: 'blur',           // 'blur' | 'change' | 'compositionEnd'
+  validateOn: 'blur',            // 'blur' | 'change' | 'submit'
+  errorMessages: {
+    katakanaOnly: 'カタカナで入力してください',
+  },
+});
+```
+
+| Option | Values | Description |
+|--------|--------|-------------|
+| `kanaMode` | `'auto-convert'` | Hiragana → Katakana auto-conversion |
+| | `'error-on-hiragana'` | Show error if Hiragana is entered |
+| `normalizeOn` | `'blur'` `'change'` `'compositionEnd'` | When to normalize |
+| `validateOn` | `'blur'` `'change'` `'submit'` | When to validate |
+
+---
+
+### usePostalCodeField
+
+For Japanese postal codes (郵便番号).
+
+```tsx
+const field = usePostalCodeField({
+  widthMode: 'half-width-only',  // or 'full-width-only'
+  onInvalid: 'auto-convert',     // or 'error'
+  autoHyphen: true,
+});
+```
+
+| Option | Values | Description |
+|--------|--------|-------------|
+| `widthMode` | `'half-width-only'` | Only allow `123-4567` |
+| | `'full-width-only'` | Only allow `１２３−４５６７` |
+| `onInvalid` | `'auto-convert'` | Auto-convert to correct width |
+| | `'error'` | Show validation error |
+| `autoHyphen` | `true` / `false` | Auto-insert hyphen |
+
+**Example:** `１２３４５６７` → `123-4567`
+
+---
+
+### usePrefectureField
+
+For Japanese prefecture (都道府県) input.
+
+```tsx
+const field = usePrefectureField({
+  autoComplete: true,
+});
+```
+
+| Option | Values | Description |
+|--------|--------|-------------|
+| `autoComplete` | `true` / `false` | Auto-complete short names |
+
+**Example:** `東京` → `東京都`, `大阪` → `大阪府`
+
+---
+
+### useAddressField
+
+For address fields with character width control.
+
+```tsx
+const field = useAddressField({
+  alphanumericMode: 'full-width-only',  // or 'allow-half-width'
+  onInvalid: 'auto-convert',
+});
+```
+
+| Option | Values | Description |
+|--------|--------|-------------|
+| `alphanumericMode` | `'full-width-only'` | Convert half-width to full-width |
+| | `'allow-half-width'` | Allow both |
+| `onInvalid` | `'auto-convert'` / `'error'` | Behavior on invalid input |
+
+**Example:** `渋谷区1-2-3` → `渋谷区１−２−３`
+
+---
+
+### usePhoneNumberField
+
+For Japanese phone numbers.
+
+```tsx
+const field = usePhoneNumberField({
+  onInvalid: 'auto-convert',
+  autoHyphen: true,
+});
+```
+
+| Option | Values | Description |
+|--------|--------|-------------|
+| `onInvalid` | `'auto-convert'` / `'error'` | Behavior on invalid input |
+| `autoHyphen` | `true` / `false` | Auto-insert hyphens |
+
+**Example:** `０９０１２３４５６７８` → `090-1234-5678`
+
+---
+
+## Return Value
+
+All hooks return the same interface:
+
+```tsx
+interface FieldReturn {
+  value: string;                    // Current value
+  onChange: (e) => void;            // Change handler
+  onBlur: (e) => void;              // Blur handler
+  onCompositionStart: (e) => void;  // IME composition start
+  onCompositionEnd: (e) => void;    // IME composition end
+  error: string | null;             // Validation error message
+  isValidating: boolean;            // Validation in progress
+  isComposing: boolean;             // IME composing state
+}
+```
+
+---
+
+## Standalone Functions
+
+Use validators and normalizers without hooks:
+
+### Validators
+
+```tsx
+import {
+  validateKatakana,
+  validateHiragana,
+  validatePostalCode,
+  validatePrefecture,
+  validatePhoneNumber,
+} from 'nihonput';
+
+validateKatakana('カタカナ');       // true
+validateKatakana('ひらがな');       // false
+
+validatePostalCode('123-4567');    // true
+validatePostalCode('1234567');     // true
+
+validatePrefecture('東京都');       // true
+validatePrefecture('東京');         // true (short form)
+
+validatePhoneNumber('090-1234-5678'); // true
+```
+
+### Normalizers
+
+```tsx
+import {
+  toKatakana,
+  toHiragana,
+  toFullWidth,
+  toHalfWidth,
+  addPostalCodeHyphen,
+  addPhoneNumberHyphen,
+} from 'nihonput';
+
+toKatakana('ひらがな');              // 'ヒラガナ'
+toHiragana('カタカナ');              // 'かたかな'
+
+toFullWidth('abc123');              // 'ａｂｃ１２３'
+toHalfWidth('１２３');               // '123'
+
+addPostalCodeHyphen('1234567');     // '123-4567'
+addPhoneNumberHyphen('09012345678'); // '090-1234-5678'
+```
+
+---
+
+## React Hook Form Integration
+
+```tsx
+import { useForm } from 'react-hook-form';
+import { toKatakana, validateKatakana } from 'nihonput';
+
+function Form() {
+  const { register, handleSubmit, setValue, formState: { errors } } = useForm();
+
+  return (
+    <form onSubmit={handleSubmit(console.log)}>
+      <input
+        {...register('furigana', {
+          validate: (v) => validateKatakana(v) || 'カタカナで入力してください',
+        })}
+        onBlur={(e) => setValue('furigana', toKatakana(e.target.value))}
+      />
+      {errors.furigana && <span>{errors.furigana.message}</span>}
+
+      <button type="submit">Submit</button>
+    </form>
+  );
+}
+```
+
+---
+
+## All Exports
+
+### Hooks
+- `useNameField`
+- `usePostalCodeField`
+- `usePrefectureField`
+- `useAddressField`
+- `usePhoneNumberField`
+
+### Validators
+- `validateKatakana` / `containsHiragana`
+- `validateHiragana` / `containsKatakana`
+- `validatePostalCode` / `isHalfWidthPostalCode` / `isFullWidthPostalCode`
+- `validatePrefecture` / `normalizePrefecture`
+- `validatePhoneNumber` / `isHalfWidthPhoneNumber`
+
+### Normalizers
+- `toKatakana` / `toHiragana`
+- `toFullWidth` / `toHalfWidth`
+- `toFullWidthNumbers` / `toHalfWidthNumbers`
+- `addPostalCodeHyphen` / `addPhoneNumberHyphen`
+
+### Constants
+- `PREFECTURES` — Array of all 47 prefectures
+- `PREFECTURE_SHORT_NAMES` — Map of short names to full names
+- `defaultErrorMessages` — Default error messages (Japanese)
+
+---
+
+## License
+
+MIT © [Hanab Labs](https://github.com/HanabLabs)