Merge pull request #731 from taro-28/add-claude-md

docs: Add CLAUDE.md for Claude Code guidance

Author: taro-28

CLAUDE.md

@@ -0,0 +1,143 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a monorepo for `tanstack-table-search-params`, a React hook library that syncs TanStack Table state with URL search parameters. The library enables table state (sorting, filtering, pagination, etc.) to persist in the URL, making it shareable and bookmarkable.
+
+## Monorepo Structure
+
+- **`packages/tanstack-table-search-params/`**: Main library package (published to npm)
+- **`packages/tsconfig/`**: Shared TypeScript configuration
+- **`examples/`**: Example implementations for different routers:
+  - `next-pages-router/`: Next.js Pages Router example
+  - `next-app-router/`: Next.js App Router example
+  - `tanstack-router/`: TanStack Router example
+  - `react-router-lib/`: React Router example
+  - `lib/`: Shared components used across examples
+
+## Development Commands
+
+### Build, Test, and Lint
+
+```bash
+# Build all packages and examples (uses Turbo)
+pnpm build
+
+# Type-check all packages
+pnpm type-check
+
+# Run tests (runs tests in main package)
+pnpm test
+
+# Lint and format with Biome
+pnpm check-write
+
+# Prettier formatting
+pnpm prettier
+
+# Check for unused dependencies
+pnpm knip
+```
+
+### Working with Specific Packages
+
+```bash
+# Main package commands
+pnpm tanstack-table-search-params <command>
+pnpm tanstack-table-search-params build
+pnpm tanstack-table-search-params test
+pnpm tanstack-table-search-params type-check
+
+# Example project commands
+pnpm examples/next-pages-router <command>
+pnpm examples/next-app-router <command>
+pnpm examples/tanstack-router <command>
+pnpm examples/react-router-lib <command>
+```
+
+### Testing
+
+```bash
+# Run tests in watch mode
+cd packages/tanstack-table-search-params
+pnpm test
+
+# Run specific test file
+pnpm test src/tests/globalFilter.test.ts
+```
+
+## Architecture
+
+### Main Hook: `useTableSearchParams`
+
+The core export is `useTableSearchParams`, which orchestrates multiple state-specific hooks:
+
+1. **State-specific hooks** (e.g., `useGlobalFilter`, `useSorting`, `usePagination`):
+   - Each manages one TanStack Table state
+   - Decodes query params → state
+   - Encodes state → query params
+   - Handles debouncing via `useDebounce`
+   - Returns state, onChange handler, and encoder function
+
+2. **Main hook** (`useTableSearchParams`):
+   - Composes all state-specific hooks
+   - Manages enabled/disabled states
+   - Provides `onStateChange` for batch updates
+   - Returns partial TableState + onChange handlers
+
+### Encoder/Decoder Pattern
+
+Each table state has paired encoder/decoder functions in `src/encoder-decoder/`:
+
+- **Decoders**: `Query → State` (e.g., `"desc"` → `[{id: "name", desc: true}]`)
+- **Encoders**: `State → Query` (e.g., `[{id: "name", desc: true}]` → `"sorting.name"`)
+- Default implementations can be customized via options
+- Exported separately for preset query params on navigation
+
+### Router Abstraction
+
+The library is router-agnostic via the `Router` type (`src/types.ts`):
+
+```typescript
+type Router = {
+  query: Query; // Current query params
+  navigate(url): void; // Navigation function (push or replace)
+  pathname: string; // Current pathname
+};
+```
+
+### Query Update Flow
+
+1. User interacts with table → TanStack Table calls onChange handler
+2. onChange handler in state-specific hook:
+   - Encodes new state to query params
+   - Calls `updateQuery()` to merge with existing query
+3. `updateQuery()` builds new URL and calls router's navigate function
+4. Router updates URL → query params change → hook re-renders with new decoded state
+
+## Testing Strategy
+
+Tests are organized in `packages/tanstack-table-search-params/src/tests/`:
+
+- **General tests**: Test with generic router mock (`testRouter.ts`)
+- **`next-pages-router/` tests**: Test Next.js-specific behavior with `next-router-mock`
+- Each state has its own test file (e.g., `globalFilter.test.ts`, `sorting.test.ts`)
+- Tests verify encoding/decoding, debouncing, and custom options
+
+## Key Implementation Details
+
+- **Supported states**: globalFilter, sorting, pagination, columnFilters, columnOrder, rowSelection, columnVisibility
+- **Default encoding**: Most states use array notation (e.g., `sorting.0.id=name&sorting.0.desc=true`)
+- **Debouncing**: Optional per-state debouncing via `useDebounce` hook
+- **Custom encoders/decoders**: Users can provide custom encoding logic (e.g., JSON, flat params)
+- **Dual exports**: Main hook from `"tanstack-table-search-params"`, encoders from `"tanstack-table-search-params/encoder-decoder"`
+
+## Build Configuration
+
+- **Builder**: tsup (`tsup.config.ts`)
+- **Entry points**: `src/index.ts` (main hook), `src/encoder-decoder/index.ts` (encoder/decoder exports)
+- **Output formats**: CJS and ESM
+- **Target**: `esnext`
+- TypeScript declarations generated automatically