udi-yac 0.8.0 → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +122 -28
- package/dist/{ce-entry-BMR0nqQT.js → ce-entry-CaIPHibV.js} +21656 -21560
- package/dist/index.d.ts +115 -13
- package/dist/udi-yac.css +1 -1
- package/dist/udi-yac.js +10953 -10583
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -115,33 +115,39 @@ Embedding in another app? Two things worth knowing up front:
|
|
|
115
115
|
|
|
116
116
|
### Config Props
|
|
117
117
|
|
|
118
|
-
| Prop
|
|
119
|
-
|
|
|
120
|
-
| `apiBaseUrl`
|
|
121
|
-
| `remotePackage`
|
|
122
|
-
| `dataPackagePath`
|
|
123
|
-
| `dataPackage`
|
|
124
|
-
| `dataFieldDomains`
|
|
125
|
-
| `fetchOptions`
|
|
126
|
-
| `authToken`
|
|
127
|
-
| `requireApiKey`
|
|
128
|
-
| `model`
|
|
129
|
-
| `downloadActions`
|
|
130
|
-
| `downloadButtonLabel`
|
|
131
|
-
| `entityIcons`
|
|
132
|
-
| `mascot`
|
|
133
|
-
| `splashMessages`
|
|
134
|
-
| `onEvent`
|
|
135
|
-
| `palette`
|
|
136
|
-
| `
|
|
137
|
-
| `
|
|
138
|
-
| `
|
|
139
|
-
| `
|
|
140
|
-
| `
|
|
141
|
-
| `
|
|
142
|
-
| `
|
|
143
|
-
| `
|
|
144
|
-
| `
|
|
118
|
+
| Prop | Type | Description |
|
|
119
|
+
| ----------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
120
|
+
| `apiBaseUrl` | `string` | Base URL for the UDIAgent API. Absolute (`https://agent.example.org`) or a same-origin path (`/api/yac`). |
|
|
121
|
+
| `remotePackage` | `string?` | Server-side data package name. Schema/domains come from `GET /v1/yac/metadata` and queries from `POST /v1/yac/query`; no CSVs load in the browser and cross-filtering becomes commit-on-mouse-up. Takes precedence over both data-package props. |
|
|
122
|
+
| `dataPackagePath` | `string?` | URL/path to `datapackage_udi.json`. Ignored when `dataPackage` is provided. |
|
|
123
|
+
| `dataPackage` | `DataPackage?` | Provide a data package object directly instead of fetching from a URL. Takes precedence over `dataPackagePath`. |
|
|
124
|
+
| `dataFieldDomains` | `DataFieldDomain[]?` | Pre-computed field domains. Skips CSV loading for domain computation when provided with `dataPackage`. |
|
|
125
|
+
| `fetchOptions` | `RequestInit?` | Custom fetch options (headers, credentials, etc.) forwarded to all data-loading fetch calls. |
|
|
126
|
+
| `authToken` | `string?` | JWT bearer token for API auth. Omit it when a backend proxy attaches the header instead; no `Authorization` header is then sent. |
|
|
127
|
+
| `requireApiKey` | `boolean?` | Show API key input before chatting |
|
|
128
|
+
| `model` | `string?` | LLM model name override |
|
|
129
|
+
| `downloadActions` | `DownloadAction[]?` | Extra items appended to the Download Data dropdown. See [Custom download actions](#custom-download-actions). |
|
|
130
|
+
| `downloadButtonLabel` | `string?` | Override the Download dropdown's trigger label. Defaults to `Download Data`. |
|
|
131
|
+
| `entityIcons` | `EntityIconMap?` | Icon overrides for entity count chips. See [Custom entity icons](#custom-entity-icons). |
|
|
132
|
+
| `mascot` | `ReactNode \| null?` | Replace or hide the welcome mascot. See [Custom mascot](#custom-mascot). |
|
|
133
|
+
| `splashMessages` | `readonly string[]?` | Override or hide the randomised prompt above the mascot. See [Custom splash messages](#custom-splash-messages). |
|
|
134
|
+
| `onEvent` | `TrackerFn?` | Analytics callback invoked on key user actions. See [Analytics events](#analytics-events). |
|
|
135
|
+
| `palette` | `UDIPalette?` | Default color palette for every chart and table. See [Custom color palette](#custom-color-palette). |
|
|
136
|
+
| `recordUrl` | `RecordUrlFn?` | Link individual records (table rows, scatter points) to their own pages. See [Record links](#record-links). |
|
|
137
|
+
| `fontScale` | `number?` | Text size multiplier (1–2) for every chart, table and label. Overrides and hides the viewer's own Text size setting; omit it to leave text size to the viewer. |
|
|
138
|
+
| `readOnly` | `boolean \| 'locked'?` | Hide the chat pane and every editing control. `'locked'` removes the user's way back out. Followed on change. See [Read-only dashboard embed](#read-only-dashboard-embed). |
|
|
139
|
+
| `onReadOnlyChange` | `(readOnly) => void` | Called when the user leaves read-only via Explore Data. See [Switching modes from the host](#switching-modes-from-the-host). |
|
|
140
|
+
| `refitOnReadOnlyChange` | `boolean?` | Re-derive the dashboard's column count for its new width when read-only changes. Defaults to `true`. See [Switching modes from the host](#switching-modes-from-the-host). |
|
|
141
|
+
| `initialSession` | `unknown?` | A session export to seed the dashboard and conversation with. See [Read-only dashboard embed](#read-only-dashboard-embed). |
|
|
142
|
+
| `savedSessionsKey` | `string?` | Adds **Saved in browser…** to the dashboard's Session menu: save the current session by name, then load or delete it later. Stored in `localStorage` under this key, so use one key per data package. |
|
|
143
|
+
| `filters` | `UDIFilter[]?` | Filters set by the embedding page. See [Filters from the host page](#filters-from-the-host-page). |
|
|
144
|
+
| `onFiltersChange` | `(filters) => void` | Called with every filter in place whenever one changes. See [Filters from the host page](#filters-from-the-host-page). |
|
|
145
|
+
| `filterMode` | `'separate' \| 'shared'?` | `'shared'` makes a host filter on one field that column's filter, which chat and chart clicks edit too. See [Filters from the host page](#filters-from-the-host-page). |
|
|
146
|
+
| `cohort` | `{ entity, fields? }?` | The table whose filtered rows to report, and their key fields (default: its `primaryKey`). See [Reporting the filtered cohort](#reporting-the-filtered-cohort). |
|
|
147
|
+
| `onCohortChange` | `(cohort) => void` | Called with the key fields of every `cohort.entity` row all filters leave, or `null` while none reaches it. See [Reporting the filtered cohort](#reporting-the-filtered-cohort). |
|
|
148
|
+
| `issueReporting` | `boolean?` | Let users report a problem to the development team: a Report an issue item in the Session menu, a button on the crash screen, and an offer from the agent. Needs LangFuse on the agent, which records reports via `POST /v1/yac/issue_report`. |
|
|
149
|
+
| `className` | `string?` | CSS class for the root element |
|
|
150
|
+
| `style` | `CSSProperties?` | Inline styles for the root element |
|
|
145
151
|
|
|
146
152
|
### Read-only dashboard embed
|
|
147
153
|
|
|
@@ -162,12 +168,46 @@ import 'udi-yac/style.css';
|
|
|
162
168
|
</div>;
|
|
163
169
|
```
|
|
164
170
|
|
|
165
|
-
**Read-only is
|
|
171
|
+
**Read-only is a mode, not a lock.** A floating "Explore Data" button at the dashboard's
|
|
166
172
|
bottom right leaves read-only, at which point the full chat and every editing control appear. The
|
|
167
173
|
chat opens fresh: the conversation `initialSession` carried is hidden, though the model still has
|
|
168
174
|
it as context for the charts on the dashboard. If your users must not be able to chat at all,
|
|
169
175
|
pass `readOnly="locked"` to `UDIChat` instead: the button is dropped, leaving no way out.
|
|
170
176
|
|
|
177
|
+
#### Switching modes from the host
|
|
178
|
+
|
|
179
|
+
`readOnly` is followed on change, so a host can show the dashboard inline and read-only, then give
|
|
180
|
+
it a bigger stage — a modal, say — with the chat, and back again. Charts, filters, brushes, the
|
|
181
|
+
conversation and a draft in the chat input all carry over, as long as it stays the **same mounted
|
|
182
|
+
`UDIChat`**: restyle its container in place rather than rendering it somewhere else. A
|
|
183
|
+
portal-based dialog remounts it and starts over; tabs beside it should hide it with CSS, not
|
|
184
|
+
unmount it.
|
|
185
|
+
|
|
186
|
+
```tsx
|
|
187
|
+
const [expanded, setExpanded] = useState(false);
|
|
188
|
+
|
|
189
|
+
<div className={expanded ? 'fixed inset-6 z-50' : 'h-[800px]'}>
|
|
190
|
+
<UDIChat
|
|
191
|
+
{...config}
|
|
192
|
+
initialSession={savedSession}
|
|
193
|
+
readOnly={!expanded}
|
|
194
|
+
onReadOnlyChange={(readOnly) => setExpanded(!readOnly)}
|
|
195
|
+
refitOnReadOnlyChange={false}
|
|
196
|
+
/>
|
|
197
|
+
</div>;
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
`onReadOnlyChange` fires when the user presses Explore Data, not when the prop changes. Passing it
|
|
201
|
+
makes the mode controlled: the button no longer leaves read-only by itself, your state setter
|
|
202
|
+
does, by changing `readOnly` in the same update that restyles the container — so the chat appears
|
|
203
|
+
in the new space with no in-between frame, and you can animate the move (a view transition, say)
|
|
204
|
+
from the read-only view still on screen. The seeded transcript is hidden the first time the chat
|
|
205
|
+
opens only; later, the conversation is the user's.
|
|
206
|
+
|
|
207
|
+
By default the dashboard re-derives its column count for its new width on each switch. Pass
|
|
208
|
+
`refitOnReadOnlyChange={false}` to keep the count — the one `initialSession` asked for, say — and
|
|
209
|
+
let the cards stretch or narrow instead.
|
|
210
|
+
|
|
171
211
|
| Removed in read-only | Kept in read-only |
|
|
172
212
|
| -------------------------------------------------------------------------- | --------------------------------------- |
|
|
173
213
|
| The chat pane and the data overview | Brushing and cross-filtering |
|
|
@@ -231,6 +271,38 @@ const [filters, setFilters] = useState<UDIFilter[]>([
|
|
|
231
271
|
A `point` filter's `selection` maps each field to the values to keep; an `interval` filter's maps
|
|
232
272
|
each field to `[min, max]`.
|
|
233
273
|
|
|
274
|
+
**Sharing columns with the chat.** By default a host filter is its own chip, read-only to the agent,
|
|
275
|
+
and applies on top of any chat or chart filter on the same column. Pass `filterMode="shared"` to
|
|
276
|
+
keep one filter per column instead: a host filter on a single field becomes that column's filter,
|
|
277
|
+
the same one the agent and chart clicks write. Whoever edits it last sets it, and
|
|
278
|
+
`onFiltersChange` reports it as `col:<entity>.<field>` with that editor's `origin`. A host can
|
|
279
|
+
then mirror chart clicks and chat requests into its own controls, matching on `dataSourceKey` and
|
|
280
|
+
field. Dropping a host entry removes the filter only while the host was its last editor. Filters
|
|
281
|
+
on several fields stay separate. Don't scope a filter to its own table: it is treated as
|
|
282
|
+
unscoped, since a plain filter already reaches every related table through its foreign keys.
|
|
283
|
+
|
|
284
|
+
### Reporting the filtered cohort
|
|
285
|
+
|
|
286
|
+
A host can follow which subjects the filters leave, to narrow its own lists to the same people.
|
|
287
|
+
Name the table and, if it has no `primaryKey`, the fields that identify its rows:
|
|
288
|
+
|
|
289
|
+
```tsx
|
|
290
|
+
<UDIChat
|
|
291
|
+
{...config}
|
|
292
|
+
cohort={{ entity: 'patient', fields: ['patient_id'] }}
|
|
293
|
+
onCohortChange={(cohort) => setPatientIds(cohort?.keys.map((k) => k.patient_id) ?? null)}
|
|
294
|
+
/>
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
- Every filter counts: chat, chart and host, on any table that reaches `entity` (directly, or
|
|
298
|
+
through a subject scope), exactly as a chart of `entity` would be filtered.
|
|
299
|
+
- `onCohortChange` gets `{ entity, keys }`, one object of key fields per row, once the filters have
|
|
300
|
+
settled (300 ms after the last change, so a brush drag runs one query). It gets `null` while no
|
|
301
|
+
filter reaches `entity`: everyone is in, and no list of every subject is sent.
|
|
302
|
+
- In server-side data mode the keys come back grouped, so the list is complete: it is not cut at
|
|
303
|
+
the package's row cap.
|
|
304
|
+
- A filter on another table reaches `entity` through a single key column, as charts do.
|
|
305
|
+
|
|
234
306
|
### Data Source Configuration
|
|
235
307
|
|
|
236
308
|
There are three ways to provide data to `UDIChat`, from simplest to most flexible:
|
|
@@ -470,6 +542,28 @@ Supply any of these to take over a channel; each one you set wins, and the rest
|
|
|
470
542
|
| `text` | Tick labels, axis and legend titles, table text. |
|
|
471
543
|
| `mutedText` | Empty cells and truncation notices. |
|
|
472
544
|
|
|
545
|
+
### Record links
|
|
546
|
+
|
|
547
|
+
Pass `recordUrl` to link individual records out to their own pages: a dataset, a donor, a patient. It is called with a row and its entity (the spec's first source) and returns that record's URL, or nothing for a row with no page.
|
|
548
|
+
|
|
549
|
+
```tsx
|
|
550
|
+
<UDIChat
|
|
551
|
+
apiBaseUrl="http://localhost:8007"
|
|
552
|
+
recordUrl={(record, entity) =>
|
|
553
|
+
typeof record.uuid === 'string'
|
|
554
|
+
? `https://portal.hubmapconsortium.org/browse/${entity.replace(/s$/, '')}/${record.uuid}`
|
|
555
|
+
: undefined
|
|
556
|
+
}
|
|
557
|
+
/>
|
|
558
|
+
```
|
|
559
|
+
|
|
560
|
+
- **Tables** gain a leading ↗ column that opens the row's page in a new tab. A table of aggregates (counts by sex, say) has no record ids, so the function returns nothing and the column is left out.
|
|
561
|
+
- **Point marks** open their record on a plain click; the cursor turns to a pointer over them. A Shift, Ctrl or ⌘ click still picks, and clicking a point keeps an existing brush. Bars, lines and areas never link.
|
|
562
|
+
- The function sees the whole row, not just the columns on screen, so it can key on a column the table doesn't show.
|
|
563
|
+
- Only `http(s)` URLs are followed. A relative URL resolves against the host page.
|
|
564
|
+
|
|
565
|
+
Independently of `recordUrl`, a table cell whose value is an `http(s)` URL — a protocol DOI, say — is always shown as a link.
|
|
566
|
+
|
|
473
567
|
### Custom mascot
|
|
474
568
|
|
|
475
569
|
The empty-dashboard welcome splash renders a YAC mascot by default. Consumers can replace it or hide it via the `mascot` prop on `UDIChatConfig`:
|