uui-data-sources

# UUI Data Sources UUI DataSources are the core infrastructure for data-driven components like PickerInput, DataTable, FiltersPanel, and PickerModal. They handle loading, filtering, sorting, selection, and tree hierarchies. ## Location - **Package:** `@epam/uui-core` - **Path:** `uui-core/src/data/processing/` - **Types:** `uui-core/src/types/dataSources.ts` ## DataSource Types | Type | Use Case | Data Flow | |------|----------|-----------| | **ArrayDataSource** | In-memory, synchronous list. Items already loaded. | Pass `items` array. Filtering/search/sorting done client-side. | | **LazyDataSource** | Server-driven, lazy loading. Large or remote data. | `api(request, context)` fetches on demand. Supports pagination, search, tree. | | **AsyncDataSource** | Fetches once via API, then caches. | `api(options)` called once; results cached and reused across views. | ## Hooks (Recommended Usage) Use hooks instead of instantiating classes directly — they handle lifecycle and prop updates: ```typescript import { useArrayDataSource, useLazyDataSource, useAsyncDataSource } from '@epam/uui-core'; ``` ### useArrayDataSource For in-memory data: ```typescript const dataSource = useArrayDataSource( { items: myItems, getId: (item) => item.id, getParentId: (item) => item.parentId, // optional, for tree }, [myItems] ); ``` ### useLazyDataSource For server-driven lazy loading: ```typescript const dataSource = useLazyDataSource<TItem, TId, TFilter>( { api: (request, context) => { // request: { filter, sorting, search, range, ids, cursor } // context: { parentId, parent } for tree children return myApi.fetchItems(request, context); }, getId: (item) => item.id, getParentId: (item) => item.parentId, }, [] ); ``` API must return `{ items: TItem[], count?: number, from?: number, cursor?: any }`. ### useAsyncDataSource Fetches once, then caches. Good for dropdowns with fixed options: ```typescript const dataSource = useAsyncDataSource( { api: (options) => svc.api.demo.countries({}, options).then((r) => r.items), getId: (item) => item.id, }, [] ); ``` ## useView and DataSourceState Components consume DataSources via `useView`: ```typescript const [dataSourceState, setDataSourceState] = useState<DataSourceState>({}); const view = dataSource.useView(dataSourceState, setDataSourceState); const rows = view.getVisibleRows(); const listProps = view.getListProps(); view.reload(); ``` **DataSourceState** (`uui-core/src/types/dataSources.ts`) includes: - `search` — search string - `filter` — filter object (passed to LazyDataSource API) - `sorting` — sort options - `checked` — checked item IDs (multi-select) - `selectedId` — single selected item - `folded` — tree node fold state - `page`, `pageSize` — pagination - `focusedIndex`, `scrollTo` — list position **SetDataSourceState** is `(update: (prev) => DataSourceState) => void` — functional update pattern. ## Key Config Options - **getId(item)** — Required. Returns unique ID. - **getParentId(item)** — Optional. For tree hierarchy. LazyDataSource uses it to load parent chain. - **complexIds** — Set `true` if IDs are objects/arrays (internally JSON.stringified). - **rowOptions** / **getRowOptions(item)** — Row-level options (selectable, checkable, editable). - **cascadeSelection** — `true` | `'explicit'` | `'implicit'` for parent-child selection behavior. - **isFoldedByDefault(item, state)** — Default fold state for tree nodes. - **selectAll** — Enable/disable select-all. Default `true`. ## LazyDataSource API Contract ```typescript type LazyDataSourceApi<TItem, TId, TFilter> = ( request: LazyDataSourceApiRequest<TItem, TId, TFilter>, context: LazyDataSourceApiRequestContext<TItem, TId> ) => Promise<LazyDataSourceApiResponse<TItem>>; ``` - **Request:** `filter`, `sorting`, `search`, `range: { from, count }`, `ids` (for specific IDs), `cursor` (pagination). - **Context:** `parentId`, `parent` when loading tree children. - **Response:** `{ items, count?, from?, cursor?, totalCount? }`. ## Common Patterns ### PickerInput with DataSource ```typescript const dataSource = useArrayDataSource({ items, getId: (i) => i.id }, [items]); <PickerInput dataSource={ dataSource } value={ value } onValueChange={ setValue } getName={ (item) => item.name } entityName="Item" /> ``` ### DataTable with DataSource ```typescript const dataSource = useArrayDataSource({ items, getId: (i) => i.id }, [items]); const [tableState, setTableState] = useState<DataTableState>({}); const view = dataSource.useView(tableState, setTableState); <DataTable getRows={ () => view.getVisibleRows() } columns={ columns } value={ tableState } onValueChange={ setTableState } /> ``` ### Tree with getParentId ```typescript const dataSource = useArrayDataSource({ items, getId: (i) => i.id, getParentId: (i) => i.parentId, }, [items]); ``` ### LazyDataSource clearCache When data changes on the server, call `dataSource.clearCache()` (LazyDataSource only) to force reload. ## References - Data source types: `uui-core/src/types/dataSources.ts` - ArrayDataSource: `uui-core/src/data/processing/ArrayDataSource.tsx` - LazyDataSource: `uui-core/src/data/processing/LazyDataSource.tsx` - AsyncDataSource: `uui-core/src/data/processing/AsyncDataSource.tsx` - Hooks: `uui-core/src/data/processing/hooks/` - Examples: `app/src/docs/_examples/dataSources/`, `app/src/docs/_examples/pickerInput/`, `app/src/docs/_examples/tables/`