Relevant source files

The following files were used as context for generating this wiki page: - [src/react/index.ts](https://github.com/CellarNode/beverage-utils/blob/main/src/react/index.ts) - [src/react/use-beverage-label-map.ts](https://github.com/CellarNode/beverage-utils/blob/main/src/react/use-beverage-label-map.ts) - [src/label-map.ts](https://github.com/CellarNode/beverage-utils/blob/main/src/label-map.ts) - [src/types.ts](https://github.com/CellarNode/beverage-utils/blob/main/src/types.ts) - [README.md](https://github.com/CellarNode/beverage-utils/blob/main/README.md) - [package.json](https://github.com/CellarNode/beverage-utils/blob/main/package.json)

# React Adapter The React Adapter for `@cellarnode/beverage-utils` provides a framework-specific interface for accessing and managing beverage classification data within React applications. It leverages [TanStack Query](https://tanstack.com/query) to handle data fetching, caching, and state management, ensuring that beverage labels and categories are available globally with minimal overhead. The adapter serves as a bridge between the core beverage utilities—specifically the label mapping logic—and React's component-based architecture. It encapsulates the complexities of asynchronous API calls to the CellarNode platform and provides a clean hook-based API for developers. Sources: [README.md:16-24](), [src/react/use-beverage-label-map.ts:1-23]() ## Architecture and Data Flow The React Adapter is built around the `useBeverageLabelMap` hook. This hook utilizes a query configuration that fetches classification data from a specified API endpoint and transforms it into a `LabelMap` using core library utilities. ### Logic Flow The data flow begins when a component calls the hook. If the data is not in the cache, it is fetched from the CellarNode API. Once received, the raw `BeverageClassification` JSON is processed by the `buildLabelMap` function to create a lookup table optimized for React rendering. ```mermaid flowchart TD A[React Component] --> B[useBeverageLabelMap] B --> C{Cache Valid?} C -- No --> D[Fetch from CellarNode API] D --> E[buildLabelMap Utility] E --> F[Update TanStack Cache] F --> G[Return LabelMap to Component] C -- Yes --> G ``` The diagram above illustrates the request lifecycle for beverage classifications within a React application. Sources: [src/react/use-beverage-label-map.ts:7-23](), [src/label-map.ts:5-15]() ## Primary Functions and Hooks The adapter exports two primary constructs for managing classification data. ### `useBeverageLabelMap(apiBaseUrl)` A custom React hook that wraps `useQuery`. It simplifies the retrieval of the label map by managing the loading and error states associated with fetching classification data. ### `beverageLabelMapOptions(apiBaseUrl)` A function returning a `queryOptions` object. This allows for prefetching or manual query management outside of the standard hook lifecycle, such as in React Router loaders or Server Components. | Feature | Description | Reference | |---|---|---| | **Query Key** | `["beverage-classifications"]` | [src/react/use-beverage-label-map.ts:9]() | | **Stale Time** | `Infinity` (Classifications rarely change) | [src/react/use-beverage-label-map.ts:19]() | | **Data Transformation** | Converts API JSON to `LabelMap` via `buildLabelMap` | [src/react/use-beverage-label-map.ts:17]() | Sources: [src/react/use-beverage-label-map.ts:7-23](), [README.md:95-104]() ## Data Structures and API Interaction The React Adapter interacts with the CellarNode API and processes data into specific TypeScript interfaces. ### API Endpoint The adapter specifically targets the following endpoint structure: `GET ${apiBaseUrl}/api/v1/classifications/beverage-types` ### Data Transformation The adapter transforms the raw `BeverageClassification` into a `LabelMap`. This map includes category IDs, subtype IDs, and composite keys (e.g., `category:subtype`) to prevent naming collisions between different beverage types. ```mermaid classDiagram class BeverageClassification { +BeverageCategory[] categories } class BeverageCategory { +string id +string name +string hsHeading +BeverageSubtype[] subtypes } class BeverageSubtype { +string id +string name +string oivType } class LabelMap { <> +string key +string value } BeverageClassification *-- BeverageCategory BeverageCategory *-- BeverageSubtype BeverageClassification ..> LabelMap : buildLabelMap() ``` This class diagram shows the relationship between the incoming API data structures and the resulting map used by React components. Sources: [src/types.ts:1-17](), [src/label-map.ts:3-15](), [src/react/use-beverage-label-map.ts:12-14]() ## Dependencies and Integration The React Adapter requires specific peer dependencies to function. These are marked as optional in the core package but are mandatory when using the `/react` export. ### Peer Dependencies - `react`: `^18.0.0` or `^19.0.0` - `@tanstack/react-query`: `^5.0.0` ### Integration Example ```tsx import { useBeverageLabelMap } from "@cellarnode/beverage-utils/react"; import { formatBeverageType } from "@cellarnode/beverage-utils"; function BeverageDisplay({ category, subtype }) { const { data: labelMap, isLoading } = useBeverageLabelMap("https://api.cellarnode.com"); if (isLoading) return

; return {formatBeverageType(category, subtype, labelMap)}; } ``` Sources: [package.json:48-56](), [README.md:86-94]() ## Summary The React Adapter provides a standardized, cached, and type-safe method for React applications to consume CellarNode beverage classifications. By integrating with TanStack Query and utilizing the core `buildLabelMap` logic, it ensures efficient data retrieval and disambiguated label formatting across different beverage categories and subtypes.