chore: add claude.md for (#739) (#740)

* chore: add claude.md for (#739)

* Update CLAUDE.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: NoopDog

CLAUDE.md

@@ -0,0 +1,214 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository Overview
+
+This is a TypeScript library package (`@databiosphere/findable-ui`) that provides reusable UI components and utilities for Data Biosphere applications, particularly the Data Browser. It compiles TypeScript source from `src/` to JavaScript in `lib/` for distribution as an npm package.
+
+**Key Facts:**
+
+- **Node Version:** 22.12.0 (enforced by package.json)
+- **UI Framework:** React 18 with Material-UI v7 and Emotion for styling
+- **Build System:** TypeScript compiler (`tsc`) with strict mode enabled
+- **Import Pattern:** External apps import as `@databiosphere/findable-ui/lib/<path>`
+
+## Development Commands
+
+### Essential Commands
+
+```bash
+# Install dependencies (use ci for clean install)
+npm ci
+
+# Compile TypeScript to lib/ directory
+npx tsc
+
+# Run all validation checks
+npm run check-format  # Prettier formatting check
+npm run lint          # ESLint with TypeScript and SonarJS plugins
+npm run test          # Jest with React Testing Library
+npm run test-compile  # TypeScript compilation check (no emit)
+
+# Development tools
+npm run storybook     # Launch Storybook on port 6006
+```
+
+### Running Single Tests
+
+```bash
+# Run specific test file
+npm test -- path/to/file.test.ts
+
+# Run tests in watch mode
+npm test -- --watch
+```
+
+### Local Development with Data Browser
+
+When developing alongside the Data Browser:
+
+1. Clone both repos in the same parent directory
+2. In findable-ui: `npm update && npx tsc`
+3. In data-browser/explorer: `npm link ../findable-ui`
+4. Rerun `npm link` if you install/uninstall packages (symlink gets removed)
+5. May need to comment out `@tanstack/react-table` in Data Browser's `next.config.mjs` webpack config
+
+**Important:** Run `npx tsc` whenever you make changes to source files that need testing in consuming apps.
+
+## Code Architecture
+
+### Directory Structure
+
+- **`/src`** - TypeScript source (compiles to `/lib`)
+  - `/components` - React UI components (organized by feature)
+  - `/hooks` - Custom React hooks (useAsync, useExploreMode, etc.)
+  - `/providers` - React context providers for state management
+  - `/theme` - MUI theme configuration
+  - `/config` - Configuration entities and utilities
+  - `/apis` - API client code (e.g., Azul API integration)
+  - `/entity` - Entity service layer (api, service, common, tsv, apicf subdirectories)
+  - `/viewModelBuilders` - Transform API responses to view models
+  - `/views` - Page-level components
+  - `/utils` - Utility functions
+  - `/types` - TypeScript type definitions
+  - `/routes` - Routing utilities
+  - `/services` - Business logic services
+  - `/common` - Shared utilities (analytics, categories, filters, etc.)
+  - `/styles` - Global styles
+- **`/tests`** - Jest test files (separate from src, not co-located)
+- **`/lib`** - Compiled JavaScript output (git-ignored, generated by tsc)
+
+### Key Architectural Patterns
+
+**Entity Service Layer:** The `/entity` directory contains a service-oriented architecture for data fetching and transformation:
+
+- `api/` - API-based entity services
+- `service/` - Service factory and models
+- `common/` - Shared client utilities
+- `tsv/` - TSV-specific services
+- `apicf/` - API custom field services
+
+**Configuration-Driven Components:** Many components are driven by config objects defined in `/config/entities.ts`. This includes analytics, authentication, export methods, and layout configuration.
+
+**Provider Architecture:** State management uses React Context providers (authentication, exploreState, fileManifestState, dataDictionary, etc.) located in `/providers`.
+
+**Analytics:** Google Analytics 4 integration via `src/common/analytics/`. Events are defined in entities.ts and tracked via the `track` function. See `src/common/analytics/readme-analytics.md` for event inventory.
+
+## Code Style Requirements
+
+### TypeScript Standards
+
+**Strict Mode Enforcement:**
+
+- All TypeScript strict checks enabled
+- **Explicit return types required** for all functions (except `.styles.ts(x)` files)
+- No `any` type (exceptions allowed in test files)
+- Strict null checks enforced
+
+**Sorting Requirements (ESLint enforced):**
+
+- Object keys must be sorted alphabetically
+- Destructured keys must be sorted
+- Interface properties must be sorted
+- String enums must be sorted
+- Imports auto-organized by prettier-plugin-organize-imports
+
+**File Naming:** Use kebab-case (e.g., `my-component.tsx`)
+
+### JSDoc Documentation
+
+**Required for all functions:**
+
+```typescript
+/**
+ * Transforms a route by removing inactivity parameters.
+ * @param routes - Array of route strings to transform.
+ * @returns The first non-login route without inactivity param, or undefined.
+ */
+function transformRoute(routes: string[]): string | undefined {
+  // implementation
+}
+```
+
+**Requirements:**
+
+- Function description
+- `@param` tags with descriptions (hyphen required before description)
+- `@returns` tag with description
+
+### React Patterns
+
+- Use functional components with hooks
+- **react-hooks/exhaustive-deps is enforced** - include all dependencies in useEffect, useCallback, useMemo
+- Styling: Use Emotion styled components in `.styles.ts` or `.styles.tsx` files
+- Component structure: Keep components focused and single-responsibility
+
+## Testing
+
+**Test Location:** Tests live in `/tests` directory (not co-located with source)
+
+**Test Framework:** Jest with `@testing-library/react` in jsdom environment
+
+**Test Naming:** Use `.test.ts` or `.test.tsx` extension
+
+**Global Mocks:** Pre-configured for ResizeObserver, TextEncoder, TextDecoder (see `tests/setup.ts`)
+
+**Test Structure:**
+
+```typescript
+describe("ComponentName", () => {
+  it("should do something specific", () => {
+    // Arrange
+    const input = "test";
+
+    // Act
+    const result = functionUnderTest(input);
+
+    // Assert
+    expect(result).toBe("expected");
+  });
+});
+```
+
+## Dependency Management
+
+**This is a library package - use peer dependencies carefully.**
+
+**Peer Dependencies:** Consuming applications must provide:
+
+- React 18.3+
+- Material-UI v7 (@mui/material, @mui/icons-material)
+- Next.js 14.2+ and next-auth
+- Emotion (@emotion/react, @emotion/styled)
+- TanStack Table and Virtual
+- Various utilities (ky, uuid, yup, etc.)
+
+**Critical:** New dependencies should go in `peerDependencies` or `devDependencies`, NOT `dependencies`.
+
+## Pre-Commit and CI Checks
+
+**All PRs must pass:**
+
+- Prettier formatting (`npm run check-format`)
+- ESLint with no errors (`npm run lint`)
+- All Jest tests passing (`npm test`)
+- TypeScript compilation (`npm run test-compile`)
+
+**Husky hooks:** Pre-commit hooks configured in `.husky/`
+
+## Common Pitfalls
+
+1. **Don't import from lib/** - Always import from `src/` during development
+2. **Don't add to dependencies** - Use peerDependencies or devDependencies
+3. **Don't disable ESLint rules** without justification
+4. **Don't skip JSDoc** - Required for all public functions
+5. **Don't commit lib/ directory** - It's build output and git-ignored
+6. **Don't skip return types** - Explicit return types required (except .styles files)
+7. **Maintain backward compatibility** - This is a library; breaking changes require major version bumps
+
+## Special Notes
+
+- **Release Management:** Uses release-please for automated versioning and changelog
+- **Storybook:** Available for component development and visual testing
+- **Import Paths:** Base URL is `./src` (configured in tsconfig.json), allowing absolute imports within src