設計原則

モバイルユーティリティは react-simplikit のコア原則を踏襲しつつ、モバイル特有の課題に合わせて拡張しています。

コア原則

React のライフサイクルを尊重し、干渉しない

react-simplikit は、React のライフサイクルに直接干渉する実装を含みません。 たとえば、useMount や useLifecycles のようなフックは提供せず、代わりに React のデフォルトの挙動を尊重し、活用するアプローチを採ります。

依存関係ゼロによる軽量さと高速さ

react-simplikit には依存関係が一切ありません。追加のライブラリに依存しないことで、プロジェクトに組み込む際のバンドルサイズを最小化し、パフォーマンス低下への懸念をなくします。

100% テストカバレッジによる信頼性の確保

react-simplikit は、すべての関数と分岐を徹底的にテストします。 基本機能だけでなく、各実装の SSR 環境における考慮事項も含めた包括的なテストを書くことで、予期しない挙動による問題を防いでいます。

わかりやすく使いやすい包括的なドキュメント

react-simplikit は、ユーザーが各機能を素早く理解し活用できるよう、詳細なドキュメントを提供します。ドキュメントには以下が含まれます。

• JSDoc コメント: 各関数の挙動、パラメータ、戻り値についての詳しい説明。
• 使用ガイド: すぐに始められる、明確でわかりやすい手順。
• 実践的な使用例: 実際のシナリオで実装を活用する方法を示す例。

完全な TypeScript サポートによる型安全性

react-simplikit は、最初から TypeScript で構築されています。すべてのフックとユーティリティには、以下が備わっています。

• 厳密な型定義: すべてのパラメータ、戻り値、オプションが完全に型付けされています
• IntelliSense サポート: IDE で自動補完とインラインドキュメントを利用できます
• ジェネリック型: 型情報を保持する柔軟な API を提供します
• any 型を使用しない: 型安全性を損なうエスケープハッチを避けています

API 設計基準

フックの戻り値

フックの戻り値については、一貫したパターンに従います。

• オブジェクト: 状態や関連する値を返す場合（例: useKeyboardHeight(): { keyboardHeight }、useVisualViewport(): { viewport }）
• void: 副作用のみを持つフックの場合（例: useBodyScrollLock(): void）

パラメータ

• 必須パラメータを先に、任意パラメータを後に配置します
• 任意パラメータが 3 個以上ある場合はオプションオブジェクトを使用します

SSR 安全パターン

すべてのフックは SSR 安全パターンに従います。

// ✅ SSR 安全 - すべてのフックがこのパターンに従います
const isClient = typeof window !== 'undefined';
if (!isClient) return defaultValue;

モバイル特有の原則

プラットフォームを意識した設計

実装においては、iOS と Android の挙動の違いを考慮します。

• Visual Viewport API の違い:
  • iOS: キーボードが表示されると offsetTop が負の値になります
  • Android: offsetTop は基本的に 0 のままです
• キーボードの高さの計算: 正確な計測のためのプラットフォーム別の処理

SSR 安全性を最優先に

すべてのフックには、安全なサーバーサイドレンダリングを保証するための SSR テストが含まれます。

it('is safe on server side rendering', () => {
  const result = renderHookSSR.serverOnly(() => useHook());
  expect(result.current).toBeDefined();
});

パフォーマンス最適化

モバイル環境ではパフォーマンスに特別な配慮が必要です。

• イベントのスロットリング／デバウンス: スクロールやリサイズのような頻発するイベントを最適化します
• パッシブイベントリスナー: 適用可能な場合はパッシブリスナーを使用します
• React トランジション: 緊急でない更新には startTransition を活用します