@databiosphere/findable-ui 47.0.2 → 49.0.0

package/.husky/pre-commit

@@ -27,6 +27,13 @@ npm test ||
 	false;
 )
 
+# Check Black (Python formatter)
+python -m black backend --check ||
+(
+	echo '🤔 Black Check Failed. Run: python -m black backend';
+	false;
+)
+
 # Check TypeScript
 npm run test-compile ||
 (

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "47.0.2"
+  ".": "49.0.0"
 }

package/.storybook/main.ts

@@ -1,52 +1,10 @@
-import { StorybookConfig } from "@storybook/nextjs";
-import * as path from "path";
+import { defineMain } from "@storybook/nextjs-vite/node";
 
-const toPath = (filePath: string) => path.join(process.cwd(), filePath);
-
-const config: StorybookConfig = {
+export default defineMain({
+  framework: "@storybook/nextjs-vite",
+  stories: ["../src/**/*.mdx", "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
   core: {
+    builder: "@storybook/builder-vite",
     disableTelemetry: true,
   },
-  stories: ["../src/**/*.stories.mdx", "../src/**/*.stories.@(js|jsx|ts|tsx)"],
-  addons: [
-    "@storybook/addon-links",
-    "@storybook/addon-essentials",
-    "@storybook/addon-interactions",
-    "@storybook/addon-mdx-gfm",
-  ],
-  typescript: {
-    reactDocgen: "react-docgen-typescript",
-    reactDocgenTypescriptOptions: {
-      shouldExtractLiteralValuesFromEnum: true,
-      // Filter out third-party props from node_modules except @mui packages
-      propFilter: (prop: any) =>
-        prop.parent
-          ? !/node_modules\/(?!@mui)/.test(prop.parent.fileName)
-          : true,
-    },
-  },
-  framework: {
-    name: "@storybook/nextjs",
-    options: {},
-  },
-  webpackFinal: async (config: any) => {
-    return {
-      ...config,
-      resolve: {
-        ...config.resolve,
-        alias: {
-          ...config.resolve.alias,
-          app: path.resolve(__dirname, "../src"),
-          //images: path.resolve(__dirname, "../images"),
-          "@emotion/core": toPath("node_modules/@emotion/react"),
-          "emotion-theming": toPath("node_modules/@emotion/react"),
-        },
-      },
-    };
-  },
-  docs: {
-    autodocs: true,
-  },
-};
-
-export default config;
+});

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Changelog
 
+## [49.0.0](https://github.com/DataBiosphere/findable-ui/compare/v48.1.0...v49.0.0) (2026-02-17)
+
+
+### ⚠ BREAKING CHANGES
+
+* chartview: add configurable bar sort order ([#772](https://github.com/DataBiosphere/findable-ui/issues/772)) (#773)
+* remove unused filemanifesttype prop and type definitions from export components ([#767](https://github.com/DataBiosphere/findable-ui/issues/767)) (#768)
+
+### Features
+
+* chartview: add configurable bar sort order ([#772](https://github.com/DataBiosphere/findable-ui/issues/772)) ([#773](https://github.com/DataBiosphere/findable-ui/issues/773)) ([bea776a](https://github.com/DataBiosphere/findable-ui/commit/bea776a987a612d30a0010f29af128946f4aad48))
+
+
+### Bug Fixes
+
+* remove unused filemanifesttype prop and type definitions from export components ([#767](https://github.com/DataBiosphere/findable-ui/issues/767)) ([#768](https://github.com/DataBiosphere/findable-ui/issues/768)) ([4da929f](https://github.com/DataBiosphere/findable-ui/commit/4da929fcfd3acaccdb60f269bbffa8be033fdec3))
+
+
+### Chores
+
+* remove debug code ([#762](https://github.com/DataBiosphere/findable-ui/issues/762)) ([#765](https://github.com/DataBiosphere/findable-ui/issues/765)) ([6a6b8f5](https://github.com/DataBiosphere/findable-ui/commit/6a6b8f5087bf972397fa4104f946b41eae03a0da))
+
+
+### Code Refactoring
+
+* render null instead of empty fragment when hideTabs is true ([#770](https://github.com/DataBiosphere/findable-ui/issues/770)) ([#771](https://github.com/DataBiosphere/findable-ui/issues/771)) ([62733b7](https://github.com/DataBiosphere/findable-ui/commit/62733b7fb271fa6be4a29b7c7d545272a1c3e9ef))
+
+## [48.1.0](https://github.com/DataBiosphere/findable-ui/compare/v48.0.0...v48.1.0) (2026-01-11)
+
+
+### Features
+
+* add debug messages to rp ([#762](https://github.com/DataBiosphere/findable-ui/issues/762)) ([#763](https://github.com/DataBiosphere/findable-ui/issues/763)) ([eb1454a](https://github.com/DataBiosphere/findable-ui/commit/eb1454a22bc27efa85e3b672330a32a775ae9763))
+
+## [48.0.0](https://github.com/DataBiosphere/findable-ui/compare/v47.0.2...v48.0.0) (2026-01-06)
+
+
+### ⚠ BREAKING CHANGES
+
+* next.js to v15.x (step towards v16) ([#714](https://github.com/DataBiosphere/findable-ui/issues/714)) (#759)
+
+### Features
+
+* added facets endpoint [#737](https://github.com/DataBiosphere/findable-ui/issues/737) ([#741](https://github.com/DataBiosphere/findable-ui/issues/741)) ([c7d4445](https://github.com/DataBiosphere/findable-ui/commit/c7d444576d3c609c5212cb8cf7a18bb64f48df4d))
+
+
+### Bug Fixes
+
+* fix "window is not defined" error in usewindowresize hook ([#742](https://github.com/DataBiosphere/findable-ui/issues/742)) ([#743](https://github.com/DataBiosphere/findable-ui/issues/743)) ([44c42a2](https://github.com/DataBiosphere/findable-ui/commit/44c42a2fb7163f710ab07991a0faef1470438559))
+
+
+### Chores
+
+* add claude.md for ([#739](https://github.com/DataBiosphere/findable-ui/issues/739)) ([#740](https://github.com/DataBiosphere/findable-ui/issues/740)) ([969b484](https://github.com/DataBiosphere/findable-ui/commit/969b4844b83725128133abf83c378125a8d78880))
+* next.js to v15.x (step towards v16) ([#714](https://github.com/DataBiosphere/findable-ui/issues/714)) ([#759](https://github.com/DataBiosphere/findable-ui/issues/759)) ([b312990](https://github.com/DataBiosphere/findable-ui/commit/b31299036707559f07271e38fc978ae8a513c157))
+* upgrade storybook to latest version ([#733](https://github.com/DataBiosphere/findable-ui/issues/733)) ([#734](https://github.com/DataBiosphere/findable-ui/issues/734)) ([b419e22](https://github.com/DataBiosphere/findable-ui/commit/b419e2226768c6182191a0936955b7ed98cfcfc3))
+
 ## [47.0.2](https://github.com/DataBiosphere/findable-ui/compare/v47.0.1...v47.0.2) (2025-12-11)
 
 

package/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

package/backend/README.md

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

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

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

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

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

package/backend/services/facets_service.py

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

@@ -0,0 +1,43 @@
+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/docs/TRUSTED_PUBLISHING.md

@@ -50,7 +50,6 @@ 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:

package/jest.config.js

@@ -1,9 +1,5 @@
 /** @type {import('ts-jest').JestConfigWithTsJest} */
 module.exports = {
-  moduleNameMapper: {
-    "^@storybook/addon-actions$":
-      "<rootDir>/src/mocks/@storybook/addon-actions.ts",
-  },
   preset: "ts-jest/presets/js-with-ts-esm",
   setupFiles: ["<rootDir>/tests/setup.ts"],
   testEnvironment: "jest-environment-jsdom",

package/lib/common/categories/config/types.d.ts

@@ -1,3 +1,4 @@
+import { Chart } from "../../chart/types";
 import { CategoryKey, DataDictionaryAnnotation, SelectCategoryValueView } from "../../entities";
 import { RangeViewKind } from "../views/range/types";
 import { SelectViewKind } from "../views/select/types";
@@ -23,6 +24,6 @@ export interface RangeCategoryConfig extends CommonCategoryConfig, RangeViewKind
  * Select category config.
  */
 export interface SelectCategoryConfig extends CommonCategoryConfig, SelectViewKind {
-    enableChartView?: boolean;
+    chart?: Chart;
     mapSelectCategoryValue?: (selectCategoryValue: SelectCategoryValueView) => SelectCategoryValueView;
 }

package/lib/common/chart/sort/constants.d.ts

@@ -0,0 +1,5 @@
+import { CHART_SORT, ChartSortFn } from "./types";
+/**
+ * Map of chart sort options to their corresponding sort functions.
+ */
+export declare const CHART_SORT_FN: Record<CHART_SORT, ChartSortFn>;

package/lib/common/chart/sort/constants.js

@@ -0,0 +1,9 @@
+import { sortCategoryValueViewsAlpha, sortCategoryValueViewsCount, } from "../../filters/sort/models/utils";
+import { CHART_SORT } from "./types";
+/**
+ * Map of chart sort options to their corresponding sort functions.
+ */
+export const CHART_SORT_FN = {
+    [CHART_SORT.ALPHA]: sortCategoryValueViewsAlpha,
+    [CHART_SORT.COUNT]: sortCategoryValueViewsCount,
+};

package/lib/common/chart/sort/types.d.ts

@@ -0,0 +1,16 @@
+import { SelectCategoryValueView } from "../../entities";
+/**
+ * Chart sorting options for select categories.
+ */
+export declare enum CHART_SORT {
+    ALPHA = "ALPHA",
+    COUNT = "COUNT"
+}
+/**
+ * Sorting function type for select category values.
+ */
+export type ChartSortFn = (a: SelectCategoryValueView, b: SelectCategoryValueView) => number;
+/**
+ * Chart sort options - either a preset (ALPHA, COUNT) or a custom sort function.
+ */
+export type ChartSortOptions = CHART_SORT | ChartSortFn;

package/lib/common/chart/sort/types.js

@@ -0,0 +1,8 @@
+/**
+ * Chart sorting options for select categories.
+ */
+export var CHART_SORT;
+(function (CHART_SORT) {
+    CHART_SORT["ALPHA"] = "ALPHA";
+    CHART_SORT["COUNT"] = "COUNT";
+})(CHART_SORT || (CHART_SORT = {}));

package/lib/common/chart/sort/utils.d.ts

@@ -0,0 +1,7 @@
+import { ChartSortOptions, ChartSortFn } from "./types";
+/**
+ * Resolves chart sort options to a sorting function.
+ * @param chartSortOptions - Chart sort option (ALPHA, COUNT, or custom function).
+ * @returns Sorting function to use for chart data.
+ */
+export declare function getChartSortFn(chartSortOptions?: ChartSortOptions): ChartSortFn;