Skip to content

CLAUDE.md

Latest commit

 

History

History
217 lines (154 loc) · 7.42 KB

CLAUDE.md

File metadata and controls

217 lines (154 loc) · 7.42 KB

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 19 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

# 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

# Run specific test file
npm test -- path/to/file.test.ts

# Run tests in watch mode
npm test -- --watch

Local Development with a Consuming App

Use scripts/link.sh to build and install a local copy of findable-ui into a consuming project (e.g. ncpi-dataset-catalog, data-browser):

# From the consuming project directory:
../findable-ui/scripts/link.sh    # Build, install, and start dev server
../findable-ui/scripts/unlink.sh  # Restore the published registry version

The link script compiles TypeScript, packs the output into a tarball, installs it with --no-save (so package.json stays unchanged), clears the Next.js cache, and starts the dev server. Ctrl+C and re-run to iterate.

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:

/**
 * 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:

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 19.2.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