@databiosphere/findable-ui 50.6.0 → 50.6.1

package/CLAUDE.md

@@ -1,214 +0,0 @@
-# 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

package/backend/README.md

@@ -1,64 +0,0 @@
-# Findable Backend (FastAPI)
-
-This folder contains a minimal FastAPI backend that exposes a stubbed **query-to-facets** endpoint for experimentation and PoC work.
-
-## Requirements
-
-- Python 3.9+
-- `pip`
-
-## Set up a Python virtual environment
-
-From the repo root:
-
-```bash
-python -m venv backend/.venv
-source backend/.venv/bin/activate
-python -m pip install --upgrade pip
-```
-
-## Install dependencies
-
-From the repo root:
-
-```bash
-pip install -r backend/requirements.txt
-```
-
-## Run the server
-
-From the repo root:
-
-```bash
-uvicorn backend.main:app --reload
-```
-
-The app will start on `http://127.0.0.1:8000` by default.
-
-## Format code
-
-From the repo root:
-
-```bash
-python -m black backend
-```
-
-### Endpoint
-
-- **Method:** `POST`
-- **Path:** `/api/v0/facets`
-- **Request body:**
-
-  ```json
-  { "query": "string" }
-  ```
-
-- **Example request:**
-
-  ```bash
-  curl -sS -X POST "http://127.0.0.1:8000/api/v0/facets" \
-    -H "Content-Type: application/json" \
-    -d '{ "query": "public bam files for latino patients with diabetes" }'
-  ```
-
-- **Response:** currently returns a **hard-coded** JSON structure representing resolved facets for the query. This is intentionally stubbed for PoC and will be replaced by a real implementation later.

package/backend/controllers/facets_controller.py

@@ -1,16 +0,0 @@
-from fastapi import APIRouter
-
-from backend.services.facets_service import compute_facets_from_query
-from backend.services.models import FacetsResponse
-
-from backend.controllers.models import FacetsRequest
-
-router = APIRouter(prefix="/api/v0/facets", tags=["facets"])
-
-
-@router.post("")
-def get_facets(payload: FacetsRequest) -> FacetsResponse:
-    """
-    Return a stubbed query-to-facets response for PoC purposes.
-    """
-    return compute_facets_from_query()

package/backend/controllers/models.py

@@ -1,11 +0,0 @@
-from pydantic import BaseModel
-
-
-class FacetsRequest(BaseModel):
-    """
-    Request model for the /api/v0/facets endpoint.
-    Attributes:
-        query (str): The search query string to retrieve facets for.
-    """
-
-    query: str

package/backend/main.py

@@ -1,8 +0,0 @@
-from fastapi import FastAPI
-
-from backend.controllers.facets_controller import router as facets_router
-
-app = FastAPI(title="Findable API")
-
-# Register controller(s)
-app.include_router(facets_router)

package/backend/requirements.txt

@@ -1,4 +0,0 @@
-fastapi==0.115.0
-uvicorn[standard]==0.30.0
-pydantic==2.9.0
-black==24.10.0

package/backend/services/facets_service.py

@@ -1,68 +0,0 @@
-from __future__ import annotations
-
-from backend.services.models import FacetsResponse
-
-
-def compute_facets_from_query() -> FacetsResponse:
-    """Return a stubbed query-to-facets response for PoC purposes.
-
-    This function will later be replaced by a real implementation that uses
-    LLM-backed intent parsing and facet resolution.
-    """
-
-    return FacetsResponse.model_validate(
-        {
-            "query": "public bam files for latino foobar patients with diabetes or foobaz",
-            "facets": [
-                {
-                    "facet": "Access",
-                    "selectedValues": [
-                        {
-                            "term": "Granted",
-                            "mention": "public",
-                        }
-                    ],
-                },
-                {
-                    "facet": "Diagnosis",
-                    "selectedValues": [
-                        {
-                            "term": "MONDO:0005015",
-                            "mention": "diabetes",  # Mention resolved but value does not exist in dev
-                        },
-                        {
-                            "term": "unknown",
-                            "mention": "foobaz",  # Mention resolved to a disease but does not match a known term
-                        },
-                    ],
-                },
-                {
-                    "facet": "File Format",
-                    "selectedValues": [
-                        {
-                            "term": ".bam",
-                            "mention": "bam",
-                        }
-                    ],
-                },
-                {
-                    "facet": "Reported Ethnicity",
-                    "selectedValues": [
-                        {
-                            "term": "Hispanic or Latino",
-                            "mention": "latino",
-                        },
-                    ],
-                },
-                {
-                    "facet": "unknown",
-                    "selectedValues": [
-                        {
-                            "term": "unknown",
-                            "mention": "foobar",  # Mention not resolved to a facet or facet term
-                        }
-                    ],
-                },
-            ],
-        }
-    )

package/backend/services/models.py

@@ -1,43 +0,0 @@
-from pydantic import BaseModel
-
-
-# Model of a selected facet value and its mention (that is, the original query text that resolved to the value).
-class SelectedValue(BaseModel):
-    """
-    Represents a selected facet value and its mention in the original query text.
-
-    Attributes:
-        term (str): The resolved facet value.
-        mention (str): The original query text that resolved to the value.
-    """
-
-    term: str
-    mention: str
-
-
-# Model of a selected facet and its resolved values.
-class FacetSelection(BaseModel):
-    """
-    Represents a selected facet and its resolved values.
-
-    Attributes:
-        facet (str): The name of the facet.
-        selectedValues (list[SelectedValue]): The list of selected values for this facet.
-    """
-
-    facet: str
-    selectedValues: list[SelectedValue]
-
-
-# Model of the selected facets for a given query, resolved and normalized via LLM.
-class FacetsResponse(BaseModel):
-    """
-    Represents the selected facets for a given query, resolved and normalized via LLM.
-
-    Attributes:
-        query (str): The original query string.
-        facets (list[FacetSelection]): The list of selected facets and their values.
-    """
-
-    query: str
-    facets: list[FacetSelection]

package/commitlint.config.js

@@ -1 +0,0 @@
-module.exports = { extends: ["@commitlint/config-conventional"] };

package/docs/TRUSTED_PUBLISHING.md

@@ -1,132 +0,0 @@
-# Trusted Publishing Setup for NPM
-
-This repository uses GitHub's trusted publishing workflow to securely publish packages to npm without using long-lived access tokens.
-
-## What is Trusted Publishing?
-
-Trusted publishing is a security feature that allows GitHub Actions to publish packages to npm using short-lived, automatically generated tokens via OpenID Connect (OIDC). This eliminates the need to store long-lived npm tokens as repository secrets, reducing the attack surface and improving supply chain security.
-
-## Configuration
-
-### GitHub Actions Workflow
-
-The `.github/workflows/release-please.yml` workflow is configured with the following settings for trusted publishing:
-
-#### Required Permissions
-
-```yaml
-permissions:
-  contents: write # Required for release-please to create releases
-  pull-requests: write # Required for release-please to create PRs
-  id-token: write # Required for trusted publishing to npm
-```
-
-The `id-token: write` permission enables the workflow to request OIDC tokens from GitHub's OIDC provider.
-
-#### Node.js Setup
-
-```yaml
-- uses: actions/setup-node@v4
-  with:
-    node-version: "22.12.0"
-    registry-url: "https://registry.npmjs.org"
-    always-auth: true # Enable authentication for trusted publishing
-```
-
-The `always-auth: true` setting ensures that authentication is enabled when publishing packages.
-
-#### Publishing with Provenance
-
-```yaml
-- name: Publish to NPM
-  run: npm publish --provenance --access public
-```
-
-The `--provenance` flag enables build provenance, which creates a publicly verifiable link between the package and its source code and build. The `--access public` flag ensures the package is published as public.
-
-## NPM Setup Requirements
-
-To enable trusted publishing for this package on npm, you need to:
-
-1. **Log in to npm** and navigate to the package settings for `@databiosphere/findable-ui`
-2. **Add a GitHub Actions Publishing Workflow**:
-   - Go to the package's publishing settings
-   - Click "Add GitHub Actions Publishing Workflow"
-   - Configure the trusted publisher with:
-     - **Repository**: `DataBiosphere/findable-ui`
-     - **Workflow**: `.github/workflows/release-please.yml`
-     - **Environment**: (leave blank, no environment is used)
-
-3. **Verify the Configuration**:
-   - Ensure the trusted publisher is listed in the package settings
-   - The workflow will use OIDC to authenticate automatically when publishing
-
-## Security Benefits
-
-- **No Long-Lived Tokens**: Eliminates the need to store npm access tokens as GitHub secrets
-- **Automatic Rotation**: Tokens are short-lived and automatically generated for each workflow run
-- **Build Provenance**: The `--provenance` flag creates verifiable attestations linking the package to its source
-- **Reduced Attack Surface**: Compromised secrets cannot be used outside the workflow context
-- **Audit Trail**: All publishes are tied to specific GitHub Actions workflow runs
-
-## Migration Notes
-
-### Removed Configuration
-
-The following configuration is no longer needed with trusted publishing:
-
-- **Repository Secret**: `DATABIOSPHERE_FINDABLE_UI_NPM_PUBLISH_TOKEN` - This secret can be safely removed from the repository settings as it is no longer used. **Important**: Only remove this secret after confirming the trusted publishing workflow works successfully in production to avoid disrupting the release process.
-- **NODE_AUTH_TOKEN Environment Variable**: No longer required in the publish step
-
-### Workflow Changes
-
-1. Added `id-token: write` permission
-2. Added `always-auth: true` to `setup-node` action
-3. Removed `NODE_AUTH_TOKEN` environment variable from publish step
-4. Added `--provenance` and `--access public` flags to `npm publish`
-
-## Testing
-
-To test the trusted publishing workflow:
-
-1. Create a test commit on a feature branch
-2. Merge to the `main` branch
-3. If the commit triggers a release (based on conventional commits), the workflow will:
-   - Create a release PR via release-please
-   - Once merged, create a GitHub release
-   - Automatically publish to npm using trusted publishing
-
-Monitor the workflow run in the Actions tab to verify successful publication.
-
-## References
-
-- [npm Trusted Publishers Documentation](https://docs.npmjs.com/trusted-publishers)
-- [GitHub: Publishing Node.js Packages](https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages/publishing-nodejs-packages-from-github-actions)
-- [npm Provenance Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [OpenID Connect in GitHub Actions](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
-## Troubleshooting
-
-### Publishing Fails with Authentication Error
-
-If the workflow fails with an authentication error:
-
-1. Verify that trusted publishing is properly configured on npm for the package
-2. Ensure the repository, workflow path, and environment (if any) match exactly in the npm settings
-3. Confirm that the workflow has the `id-token: write` permission
-
-### Provenance Attestation Not Generated
-
-If the package is published but provenance is not attached:
-
-1. Ensure the `--provenance` flag is included in the `npm publish` command
-2. Verify that the workflow has `id-token: write` permission
-3. Check that the package is being published from a supported environment (GitHub Actions)
-
-### Package Access Issues
-
-If the package fails to publish due to access issues:
-
-1. Ensure the `--access public` flag is set (for public packages)
-2. Verify that the npm package settings allow public access
-3. Confirm that the organization and package name are correct

package/jest.config.js

@@ -1,6 +0,0 @@
-/** @type {import('ts-jest').JestConfigWithTsJest} */
-module.exports = {
-  preset: "ts-jest/presets/js-with-ts-esm",
-  setupFiles: ["<rootDir>/tests/setup.ts"],
-  testEnvironment: "jest-environment-jsdom",
-};

package/release-please-config.json

@@ -1,23 +0,0 @@
-{
-  "monorepo-tags": false,
-  "packages": {
-    ".": {
-      "release-type": "node",
-      "component": "",
-      "include-component-in-tag": false
-    }
-  },
-  "changelog-sections": [
-    { "type": "feat", "section": "Features" },
-    { "type": "fix", "section": "Bug Fixes" },
-    { "type": "chore", "section": "Chores" },
-    { "type": "content", "section": "Content" },
-    { "type": "docs", "section": "Documentation" },
-    { "type": "style", "section": "Styles" },
-    { "type": "refactor", "section": "Code Refactoring" },
-    { "type": "perf", "section": "Performance Improvements" },
-    { "type": "test", "section": "Tests" },
-    { "type": "build", "section": "Build System" },
-    { "type": "ci", "section": "Continuous Integration" }
-  ]
-}