@dudousxd/nestjs-catalog-react 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.
Files changed (47) hide show
  1. package/README.md +41 -5
  2. package/dist/DashboardBoard.d.ts +22 -0
  3. package/dist/DashboardBoard.js +88 -67
  4. package/dist/GovernanceTimeline.js +11 -1
  5. package/dist/SavedQueryPanel.d.ts +0 -8
  6. package/dist/SavedQueryPanel.js +48 -9
  7. package/dist/charts/body.d.ts +39 -0
  8. package/dist/charts/body.js +53 -0
  9. package/dist/charts/grid.d.ts +23 -0
  10. package/dist/charts/grid.js +39 -0
  11. package/dist/context.d.ts +71 -0
  12. package/dist/context.js +20 -3
  13. package/dist/embed/EmbeddedChart.d.ts +41 -0
  14. package/dist/embed/EmbeddedChart.js +25 -0
  15. package/dist/embed/EmbeddedDashboard.d.ts +32 -0
  16. package/dist/embed/EmbeddedDashboard.js +38 -0
  17. package/dist/embed/actions.d.ts +75 -0
  18. package/dist/embed/actions.js +64 -0
  19. package/dist/embed/chart-card.d.ts +20 -0
  20. package/dist/embed/chart-card.js +89 -0
  21. package/dist/embed/index.d.ts +12 -0
  22. package/dist/embed/index.js +11 -0
  23. package/dist/embed/payload.d.ts +78 -0
  24. package/dist/embed/payload.js +42 -0
  25. package/dist/embed/slots.d.ts +52 -0
  26. package/dist/embed/slots.js +44 -0
  27. package/dist/export/css-variables.d.ts +60 -0
  28. package/dist/export/css-variables.js +137 -0
  29. package/dist/export/index.d.ts +21 -0
  30. package/dist/export/index.js +21 -0
  31. package/dist/export/pdf.d.ts +136 -0
  32. package/dist/export/pdf.js +97 -0
  33. package/dist/export/png.d.ts +88 -0
  34. package/dist/export/png.js +125 -0
  35. package/dist/export/serialize.d.ts +92 -0
  36. package/dist/export/serialize.js +298 -0
  37. package/dist/export/use-pdf-export.d.ts +66 -0
  38. package/dist/export/use-pdf-export.js +63 -0
  39. package/dist/export/use-png-export.d.ts +82 -0
  40. package/dist/export/use-png-export.js +126 -0
  41. package/dist/index.d.ts +3 -1
  42. package/dist/index.js +21 -1
  43. package/dist/routes.d.ts +25 -1
  44. package/dist/routes.js +25 -1
  45. package/dist/sharing.d.ts +81 -0
  46. package/dist/sharing.js +72 -0
  47. package/package.json +2 -2
@@ -0,0 +1,39 @@
1
+ /**
2
+ * The grid a board of cards is laid out on, and the span a card takes in it.
3
+ *
4
+ * Shared by the console's `DashboardBoard` and by `<EmbeddedDashboard>` so that
5
+ * the same dashboard, embedded in somebody else's app, is arranged the way its
6
+ * author arranged it. The two halves have to travel together: the span classes
7
+ * below are meaningless unless the parent declared exactly {@link CHART_GRID},
8
+ * and a copy of one without the other is how a four-wide card ends up spanning
9
+ * past the end of a two-column grid.
10
+ *
11
+ * Container queries, not viewport ones. A board sits beside whatever the host
12
+ * put next to it, so how much room a card actually has is a fact about THIS box
13
+ * and not about the window — `md:` here would give two columns on an 800px
14
+ * screen whose board is 500px wide. The parent must therefore declare
15
+ * `@container` itself; the console does it on its scroll region.
16
+ */
17
+ export const CHART_GRID = 'grid grid-cols-1 gap-4 @2xl:grid-cols-2 @5xl:grid-cols-4';
18
+ /**
19
+ * The width an author chose, applied only where there are columns to spend.
20
+ *
21
+ * Below `@5xl` the grid has fewer than four columns, and a `col-span-4` there
22
+ * spans past the end — which is what put a chart's axis labels outside its own
23
+ * card. Every card is full width on a narrow board, two-up in the middle, and
24
+ * only honours the chosen span once four columns exist to divide.
25
+ */
26
+ const SPAN = {
27
+ 1: '@5xl:col-span-1',
28
+ 2: '@2xl:col-span-2 @5xl:col-span-2',
29
+ 3: '@2xl:col-span-2 @5xl:col-span-3',
30
+ 4: '@2xl:col-span-2 @5xl:col-span-4',
31
+ };
32
+ /**
33
+ * Half the board is the default for a width nobody set or one nothing can
34
+ * honour — a stored card is JSON, so `width` arrives as whatever was written,
35
+ * and a missing class would silently collapse the card to one column.
36
+ */
37
+ export function chartSpan(width) {
38
+ return SPAN[width ?? 2] ?? SPAN[2];
39
+ }
package/dist/context.d.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  import type { CatalogAuditEvent, CatalogConnection, CatalogConnector, CatalogObjectPage, CatalogQueryRelation, CatalogQueryResult, CatalogSnapshot, CatalogTraceList, CatalogTransform, ConnectionCheck, ConnectorRun, Dashboard, DashboardCard, ObjectQueryParams, PropertyPatch, SaveQueryInput, SavedQuery, TraceQuery, TransformLanguage, TransformResult, TypePatch } from '@dudousxd/nestjs-catalog/client';
2
2
  import { type ReactNode } from 'react';
3
+ import type { EmbeddedChartPayload, EmbeddedDashboardPayload } from './embed/payload';
3
4
  import { type PeopleQuery } from './routes';
4
5
  import type { CatalogWorkflow, WorkflowDurability, WorkflowInput, WorkflowRun } from './workflow/model';
5
6
  /**
@@ -15,6 +16,29 @@ export interface CatalogTransport {
15
16
  patch<T>(path: string, body: unknown): Promise<T>;
16
17
  post<T>(path: string, body?: unknown): Promise<T>;
17
18
  delete<T>(path: string): Promise<T>;
19
+ /**
20
+ * Where this transport would send `path`, as a URL a browser can navigate to.
21
+ *
22
+ * The one thing a `Promise`-returning method cannot express. An export is a
23
+ * GET that streams a file: the browser downloads it without this library
24
+ * touching the response, which is what lets the control be a link that can be
25
+ * copied, bookmarked or handed to a download manager. `exportUrl` is the only
26
+ * caller.
27
+ *
28
+ * It exists because `exportUrl` used to answer `/api${path}` — the single
29
+ * hardcoded mount point in a package whose whole argument (see `routes.ts`,
30
+ * which makes it verbatim) is that the transport is the only thing that knows
31
+ * where the API lives. Worse, the component it broke first is the embedded
32
+ * chart, which by definition runs inside an application that mounted this
33
+ * catalog wherever it liked.
34
+ *
35
+ * Optional so an existing transport keeps compiling, and a transport that
36
+ * does not answer gets the path exactly as written — right only where the API
37
+ * is served from the root. Implement it if your transport prepends anything
38
+ * at all; it is the same concatenation the four methods above already do, and
39
+ * the console's own does it in one line.
40
+ */
41
+ url?(path: string): string;
18
42
  }
19
43
  /**
20
44
  * What this deployment can actually execute.
@@ -201,18 +225,56 @@ export interface CatalogClient {
201
225
  }>;
202
226
  exportUrl(id: string): string;
203
227
  listDashboards(): Promise<Dashboard[]>;
228
+ /**
229
+ * `shared` is declared on both writes, and it is not decoration.
230
+ *
231
+ * The server's `patchDashboard` says why one layer down: a field a body type
232
+ * does not name is a field a host's whitelisting `ValidationPipe` deletes, so
233
+ * the write appears to succeed and the flag never moves. This type dropped it
234
+ * again — and a field a CLIENT type does not name cannot even be passed, so
235
+ * the failure arrives earlier and reads as a compile error in the one screen
236
+ * that would have set it.
237
+ *
238
+ * What that cost: `shared` is the entire access boundary of the embed API, so
239
+ * every dashboard a shipped console produced was un-embeddable, `embedDashboard`
240
+ * answered `403` for all of them, and `<EmbeddedDashboard>`'s "Nothing on this
241
+ * dashboard has been shared" was not an empty state but the only state.
242
+ *
243
+ * On `saveDashboard` too, although the console's create form does not offer
244
+ * it — a board is created empty and there is nothing yet to share. The field
245
+ * is here because the route accepts it and a host driving this client
246
+ * directly should not have to discover that the two writes disagree.
247
+ */
204
248
  saveDashboard(input: {
205
249
  name: string;
206
250
  description?: string;
251
+ shared?: boolean;
207
252
  }): Promise<Dashboard>;
208
253
  updateDashboard(id: string, input: Partial<{
209
254
  name: string;
210
255
  description: string;
211
256
  cards: DashboardCard[];
257
+ shared: boolean;
212
258
  }>): Promise<Dashboard>;
213
259
  deleteDashboard(id: string): Promise<{
214
260
  deleted: boolean;
215
261
  }>;
262
+ /**
263
+ * What another application may render.
264
+ *
265
+ * Reads only, and rendered rather than executable: a chart comes back as
266
+ * columns and rows with a visualization, never as SQL, so an embed cannot ask
267
+ * for anything the sharer did not already share. Both refuse anything not
268
+ * explicitly marked shared in the console, which is why there is no
269
+ * `embedQuery(sql)` and never will be.
270
+ *
271
+ * `exportUrl` above is what an embedded chart's CSV action links to — the
272
+ * same export the console uses, because it is the same saved query, and
273
+ * resolved through the transport so it points at wherever the HOST mounted
274
+ * this catalog rather than at wherever the console happens to live.
275
+ */
276
+ embedChart(id: string): Promise<EmbeddedChartPayload>;
277
+ embedDashboard(id: string): Promise<EmbeddedDashboardPayload>;
216
278
  listEvents(query: {
217
279
  event?: string;
218
280
  typeName?: string;
@@ -353,6 +415,15 @@ export declare const catalogQueryKeys: {
353
415
  transforms: readonly ["nestjs-catalog", "pipeline", "transforms"];
354
416
  runs: (connectorId?: string) => readonly ["nestjs-catalog", "pipeline", "runs", string];
355
417
  workflows: readonly ["nestjs-catalog", "pipeline", "workflows"];
418
+ /**
419
+ * The embed keys, under one prefix so a host can invalidate every embedded
420
+ * chart on its page at once — which is the only refresh an embed has. The
421
+ * components deliberately ship no refresh control of their own, so this is
422
+ * the seam a host uses to decide when its own page reloads its data.
423
+ */
424
+ embed: readonly ["nestjs-catalog", "embed"];
425
+ embeddedChart: (id: string) => readonly ["nestjs-catalog", "embed", "chart", string];
426
+ embeddedDashboard: (id: string) => readonly ["nestjs-catalog", "embed", "dashboard", string];
356
427
  access: readonly ["nestjs-catalog", "access"];
357
428
  principals: readonly ["nestjs-catalog", "access", "principals"];
358
429
  people: readonly ["nestjs-catalog", "access", "people"];
package/dist/context.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import { jsx as _jsx } from "react/jsx-runtime";
2
2
  import { catalogRoutes } from '@dudousxd/nestjs-catalog/client';
3
3
  import { createContext, useContext, useMemo } from 'react';
4
- import { DEFAULT_ACCESS_BASE_PATH, DEFAULT_PIPELINE_BASE_PATH, accessRoutes, pipelineRoutes, } from './routes';
4
+ import { DEFAULT_ACCESS_BASE_PATH, DEFAULT_PIPELINE_BASE_PATH, accessRoutes, embedRoutes, pipelineRoutes, } from './routes';
5
5
  const CatalogContext = createContext(null);
6
6
  export function CatalogProvider({ transport, pipelineBasePath = DEFAULT_PIPELINE_BASE_PATH, accessBasePath = DEFAULT_ACCESS_BASE_PATH, children, }) {
7
7
  const client = useMemo(() => {
@@ -24,12 +24,20 @@ export function CatalogProvider({ transport, pipelineBasePath = DEFAULT_PIPELINE
24
24
  deleteSavedQuery: (id) => transport.delete(catalogRoutes.savedQuery(id)),
25
25
  runSavedQuery: (id) => transport.post(catalogRoutes.runSavedQuery(id), {}),
26
26
  // A URL rather than a fetch: an export the browser downloads itself can
27
- // be a link, and a link can be copied, bookmarked or scheduled.
28
- exportUrl: (id) => `/api${catalogRoutes.exportSavedQuery(id)}`,
27
+ // be a link, and a link can be copied, bookmarked or scheduled. Where
28
+ // that link points is the transport's answer, exactly like every other
29
+ // request this client makes — see `CatalogTransport.url` for what this
30
+ // hardcoded `/api` used to cost.
31
+ exportUrl: (id) => {
32
+ const path = catalogRoutes.exportSavedQuery(id);
33
+ return transport.url ? transport.url(path) : path;
34
+ },
29
35
  listDashboards: () => transport.get(catalogRoutes.dashboards()),
30
36
  saveDashboard: (input) => transport.post(catalogRoutes.dashboards(), input),
31
37
  updateDashboard: (id, input) => transport.patch(catalogRoutes.dashboard(id), input),
32
38
  deleteDashboard: (id) => transport.delete(catalogRoutes.dashboard(id)),
39
+ embedChart: (id) => transport.get(embedRoutes.chart(id)),
40
+ embedDashboard: (id) => transport.get(embedRoutes.dashboard(id)),
33
41
  listEvents: (query) => transport.get(catalogRoutes.events(), { ...query }),
34
42
  listTraces: (query) => transport.get(catalogRoutes.traces(), { ...query }),
35
43
  pipelineCapabilities: () => transport.get(pipeline.capabilities()),
@@ -89,6 +97,15 @@ export const catalogQueryKeys = {
89
97
  transforms: ['nestjs-catalog', 'pipeline', 'transforms'],
90
98
  runs: (connectorId) => ['nestjs-catalog', 'pipeline', 'runs', connectorId ?? 'all'],
91
99
  workflows: ['nestjs-catalog', 'pipeline', 'workflows'],
100
+ /**
101
+ * The embed keys, under one prefix so a host can invalidate every embedded
102
+ * chart on its page at once — which is the only refresh an embed has. The
103
+ * components deliberately ship no refresh control of their own, so this is
104
+ * the seam a host uses to decide when its own page reloads its data.
105
+ */
106
+ embed: ['nestjs-catalog', 'embed'],
107
+ embeddedChart: (id) => ['nestjs-catalog', 'embed', 'chart', id],
108
+ embeddedDashboard: (id) => ['nestjs-catalog', 'embed', 'dashboard', id],
92
109
  access: ['nestjs-catalog', 'access'],
93
110
  principals: ['nestjs-catalog', 'access', 'principals'],
94
111
  people: ['nestjs-catalog', 'access', 'people'],
@@ -0,0 +1,41 @@
1
+ import type { EmbedActions } from './actions';
2
+ import { type EmbedFailureSlot, type EmbedLoadingSlot } from './slots';
3
+ /**
4
+ * One shared chart, for a host application's own page.
5
+ *
6
+ * Not a console screen. This is the component somebody drops into an internal
7
+ * tool or a customer-facing page to show a chart that was authored, saved and
8
+ * shared somewhere else — so it renders the answer and nothing that could
9
+ * change it. Everything that assembles a board (refresh, delete, the width and
10
+ * library pickers, the drag handle) belongs to `<DashboardBoard />`, which is
11
+ * where a person with the scope to author actually is.
12
+ *
13
+ * What it needs from the host: a `<CatalogProvider>` for the transport, a
14
+ * `QueryClientProvider` above that, and a principal holding `catalog:embed`.
15
+ * The server answers only for a saved query that has been explicitly marked
16
+ * shared — an id alone is not access.
17
+ */
18
+ export interface EmbeddedChartProps {
19
+ /**
20
+ * The saved query's id, exactly as `GET /catalog/embed` lists it.
21
+ *
22
+ * Discovering ids is the host's job — hardcode one, or read the discovery
23
+ * endpoint through its own transport. This component takes an id rather than
24
+ * a name because a name is not stable and a chart that silently swapped for
25
+ * another one on rename is worse than a chart that stops loading.
26
+ */
27
+ chartId: string;
28
+ /**
29
+ * Which output controls to draw. Defaults to `'none'`: an embed is inert
30
+ * unless the host asks for something.
31
+ */
32
+ actions?: EmbedActions;
33
+ /** What to show while fetching. A node, or a function returning one. */
34
+ loading?: EmbedLoadingSlot;
35
+ /** What to show when the fetch failed. Receives the error, if a function. */
36
+ failure?: EmbedFailureSlot;
37
+ /** Rough pixel height for the chart body. The loading state matches it. */
38
+ height?: number;
39
+ className?: string;
40
+ }
41
+ export declare function EmbeddedChart({ chartId, actions, loading, failure, height, className, }: EmbeddedChartProps): import("react/jsx-runtime").JSX.Element;
@@ -0,0 +1,25 @@
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ import { useQuery } from '@tanstack/react-query';
3
+ import { cn } from '../cn';
4
+ import { catalogQueryKeys, useCatalogClient } from '../context';
5
+ import { EmbeddedChartCard } from './chart-card';
6
+ import { renderFailure, renderLoading, } from './slots';
7
+ export function EmbeddedChart({ chartId, actions, loading, failure, height = 200, className, }) {
8
+ const client = useCatalogClient();
9
+ const { data, isPending, error } = useQuery({
10
+ queryKey: catalogQueryKeys.embeddedChart(chartId),
11
+ queryFn: () => client.embedChart(chartId),
12
+ });
13
+ // Three states kept apart, in the order that matters: an error is not a
14
+ // pending fetch, and neither is a chart. React Query keeps `data` from the
15
+ // last success while a background refetch runs, so `isPending` — never
16
+ // `isFetching` — is what decides, or the host's page would flash a
17
+ // placeholder over a chart that is already on screen.
18
+ if (error) {
19
+ return _jsx("div", { className: cn('min-w-0', className), children: renderFailure(failure, error, height) });
20
+ }
21
+ if (isPending) {
22
+ return _jsx("div", { className: cn('min-w-0', className), children: renderLoading(loading, height) });
23
+ }
24
+ return _jsx(EmbeddedChartCard, { chart: data, actions: actions, height: height, className: className });
25
+ }
@@ -0,0 +1,32 @@
1
+ import type { ReactNode } from 'react';
2
+ import type { EmbedActions } from './actions';
3
+ import { type EmbedFailureSlot, type EmbedLoadingSlot } from './slots';
4
+ /**
5
+ * A whole shared dashboard, in a host application's own page.
6
+ *
7
+ * ONE request, not one per card: the server resolves every chart of a shared
8
+ * dashboard in a single response, and a card whose query is broken or unshared
9
+ * is left out rather than failing the page. That is also why this is not a loop
10
+ * of `<EmbeddedChart>` — that would be N round trips from somebody else's
11
+ * frontend against a database this deployment owns, which is precisely the load
12
+ * pattern the embed API was shaped to avoid.
13
+ *
14
+ * Same rule as the single chart: output only. Nothing here can reorder, resize,
15
+ * delete or re-run anything; the board is arranged in the console.
16
+ */
17
+ export interface EmbeddedDashboardProps {
18
+ /** The dashboard's id, exactly as `GET /catalog/embed` lists it. */
19
+ dashboardId: string;
20
+ /** Which output controls each chart draws. Defaults to `'none'`. */
21
+ actions?: EmbedActions;
22
+ /** What to show while fetching. A node, or a function returning one. */
23
+ loading?: EmbedLoadingSlot;
24
+ /** What to show when the fetch failed. Receives the error, if a function. */
25
+ failure?: EmbedFailureSlot;
26
+ /** Rough pixel height for each chart body. */
27
+ height?: number;
28
+ /** Shown when the dashboard resolved but every card was left out. */
29
+ empty?: ReactNode;
30
+ className?: string;
31
+ }
32
+ export declare function EmbeddedDashboard({ dashboardId, actions, loading, failure, height, empty, className, }: EmbeddedDashboardProps): import("react/jsx-runtime").JSX.Element;
@@ -0,0 +1,38 @@
1
+ import { jsx as _jsx } from "react/jsx-runtime";
2
+ import { useQuery } from '@tanstack/react-query';
3
+ import { CHART_GRID, chartSpan } from '../charts/grid';
4
+ import { cn } from '../cn';
5
+ import { catalogQueryKeys, useCatalogClient } from '../context';
6
+ import { EmbeddedChartCard } from './chart-card';
7
+ import { chartsInLayoutOrder } from './payload';
8
+ import { renderFailure, renderLoading, } from './slots';
9
+ export function EmbeddedDashboard({ dashboardId, actions, loading, failure, height = 200, empty, className, }) {
10
+ const client = useCatalogClient();
11
+ const { data, isPending, error } = useQuery({
12
+ queryKey: catalogQueryKeys.embeddedDashboard(dashboardId),
13
+ queryFn: () => client.embedDashboard(dashboardId),
14
+ });
15
+ if (error) {
16
+ return _jsx("div", { className: cn('min-w-0', className), children: renderFailure(failure, error, height) });
17
+ }
18
+ if (isPending) {
19
+ return _jsx("div", { className: cn('min-w-0', className), children: renderLoading(loading, height) });
20
+ }
21
+ const charts = chartsInLayoutOrder(data.charts);
22
+ return (
23
+ // `@container` here rather than on the host's element, because the grid
24
+ // below is sized by container queries and the container has to be declared
25
+ // by whoever owns the box — a host that forgot would get a one-column
26
+ // board on a 2000px page and no way to tell why.
27
+ _jsx("div", { className: cn('@container min-w-0', className), children: charts.length === 0 ? (
28
+ // Not the same as a failure, and said differently. Every card of a
29
+ // shared dashboard can be dropped — each one's own saved query has to
30
+ // be shared too — and a blank page with an error on it would send the
31
+ // reader to the wrong place entirely.
32
+ (empty ?? (_jsx("p", { className: "px-4 py-8 text-center text-xs text-zinc-400 dark:text-zinc-500", children: "Nothing on this dashboard has been shared." })))) : (_jsx("div", { className: CHART_GRID, children: charts.map((chart) => (
33
+ // The author's width, honoured through the same span map the
34
+ // console uses. `min-w-0` because a grid item defaults to
35
+ // `min-width: auto`, and a chart wider than its column pushes the
36
+ // column out instead of being constrained by it.
37
+ _jsx("div", { className: cn(chartSpan(chart.layout?.width), 'min-w-0'), children: _jsx(EmbeddedChartCard, { chart: chart, actions: actions, height: height }) }, chart.id))) })) }));
38
+ }
@@ -0,0 +1,75 @@
1
+ import { type PngExportTarget } from '../export/use-png-export';
2
+ /**
3
+ * What an embedded chart's toolbar may offer.
4
+ *
5
+ * OUTPUT ONLY, and the union is the enforcement. An embed is a chart in
6
+ * somebody else's application: the board was assembled in the console, and the
7
+ * controls that assemble it — refresh, delete, the chart-library picker, the
8
+ * width picker, the drag handle — have no meaning in a host's page and real
9
+ * costs there. A refresh button is the clearest case: it would run the query
10
+ * again on demand, straight past whatever caching the host put in front of this
11
+ * component, from a page the catalog's operators do not control.
12
+ *
13
+ * Only actions that exist appear here. An option that does nothing is worse
14
+ * than a missing one — a host ships it, a user clicks it, and the bug report
15
+ * arrives against the host.
16
+ *
17
+ * Being in this union is necessary and NOT sufficient. `'png'` cannot be
18
+ * produced from the built-in CSS bar chart, which draws with divs rather than
19
+ * an `<svg>`; `'pdf'` needs the host to have registered an exporter, because
20
+ * this package ships no PDF dependency. Both are decided per card at render
21
+ * time — see {@link useAvailableEmbedActions}, which is what the toolbar
22
+ * actually draws from.
23
+ */
24
+ export type EmbedAction = 'csv' | 'png' | 'pdf';
25
+ /**
26
+ * Every action, in the order a toolbar draws them.
27
+ *
28
+ * The canonical order lives here rather than being taken from whatever a caller
29
+ * passed, so two embeds asking for the same set look the same. This is also the
30
+ * one place a new action is added: append it, and `'all'`, the filter below and
31
+ * the toolbar's switch all pick it up.
32
+ */
33
+ export declare const EMBED_ACTIONS: readonly EmbedAction[];
34
+ /**
35
+ * What the host asked for.
36
+ *
37
+ * `'none'` is the default, not `'all'` — see {@link resolveEmbedActions}.
38
+ */
39
+ export type EmbedActions = 'all' | 'none' | EmbedAction[];
40
+ /**
41
+ * The actions to draw, from what the host asked for.
42
+ *
43
+ * Defaults to NOTHING. An embed should be inert unless the host asks for a
44
+ * control: it is rendering inside a page with its own affordances, its own
45
+ * toolbar and its own ideas about what a user may do, and a library that adds
46
+ * unrequested buttons to somebody else's UI is a library that has to be styled
47
+ * back out again.
48
+ *
49
+ * A list is filtered against {@link EMBED_ACTIONS} rather than trusted. The
50
+ * union makes an unknown value a compile error, but this component is exported
51
+ * from a published package and plenty of callers are not compiling anything —
52
+ * an untyped `['csv', 'pdf']` from a JS host must draw the CSV button and
53
+ * silently drop the other, not render a control with no behaviour behind it.
54
+ * Filtering in this direction also dedupes, which is why `['csv', 'csv']` gives
55
+ * one button.
56
+ */
57
+ export declare function resolveEmbedActions(actions?: EmbedActions): EmbedAction[];
58
+ /**
59
+ * Whether each requested action can actually be performed on THIS card.
60
+ *
61
+ * Asking for an action and being able to do it are different questions, and the
62
+ * union can only answer the first. A chart drawn by the built-in renderer is
63
+ * divs, so there is no `<svg>` to rasterise and no PNG; a PDF needs the host to
64
+ * have registered an exporter, and most hosts never will.
65
+ *
66
+ * Filtering here rather than letting each control return null is what keeps the
67
+ * toolbar's exhaustive `switch` meaningful: every action it is handed IS
68
+ * drawable, so the `never` at the bottom still means "you added a member and
69
+ * forgot to draw it" rather than "this one sometimes draws nothing".
70
+ *
71
+ * It also means an empty toolbar is a real answer. A host that asked for `'all'`
72
+ * on a CSS-drawn chart with no PDF exporter gets the CSV link and nothing else,
73
+ * rather than three buttons of which two apologise.
74
+ */
75
+ export declare function useAvailableEmbedActions(actions: EmbedActions | undefined, target: PngExportTarget): EmbedAction[];
@@ -0,0 +1,64 @@
1
+ import { usePdfExport } from '../export/use-pdf-export';
2
+ import { useHasExportableSvg } from '../export/use-png-export';
3
+ /**
4
+ * Every action, in the order a toolbar draws them.
5
+ *
6
+ * The canonical order lives here rather than being taken from whatever a caller
7
+ * passed, so two embeds asking for the same set look the same. This is also the
8
+ * one place a new action is added: append it, and `'all'`, the filter below and
9
+ * the toolbar's switch all pick it up.
10
+ */
11
+ export const EMBED_ACTIONS = ['csv', 'png', 'pdf'];
12
+ /**
13
+ * The actions to draw, from what the host asked for.
14
+ *
15
+ * Defaults to NOTHING. An embed should be inert unless the host asks for a
16
+ * control: it is rendering inside a page with its own affordances, its own
17
+ * toolbar and its own ideas about what a user may do, and a library that adds
18
+ * unrequested buttons to somebody else's UI is a library that has to be styled
19
+ * back out again.
20
+ *
21
+ * A list is filtered against {@link EMBED_ACTIONS} rather than trusted. The
22
+ * union makes an unknown value a compile error, but this component is exported
23
+ * from a published package and plenty of callers are not compiling anything —
24
+ * an untyped `['csv', 'pdf']` from a JS host must draw the CSV button and
25
+ * silently drop the other, not render a control with no behaviour behind it.
26
+ * Filtering in this direction also dedupes, which is why `['csv', 'csv']` gives
27
+ * one button.
28
+ */
29
+ export function resolveEmbedActions(actions = 'none') {
30
+ if (actions === 'none')
31
+ return [];
32
+ if (actions === 'all')
33
+ return [...EMBED_ACTIONS];
34
+ return EMBED_ACTIONS.filter((action) => actions.includes(action));
35
+ }
36
+ /**
37
+ * Whether each requested action can actually be performed on THIS card.
38
+ *
39
+ * Asking for an action and being able to do it are different questions, and the
40
+ * union can only answer the first. A chart drawn by the built-in renderer is
41
+ * divs, so there is no `<svg>` to rasterise and no PNG; a PDF needs the host to
42
+ * have registered an exporter, and most hosts never will.
43
+ *
44
+ * Filtering here rather than letting each control return null is what keeps the
45
+ * toolbar's exhaustive `switch` meaningful: every action it is handed IS
46
+ * drawable, so the `never` at the bottom still means "you added a member and
47
+ * forgot to draw it" rather than "this one sometimes draws nothing".
48
+ *
49
+ * It also means an empty toolbar is a real answer. A host that asked for `'all'`
50
+ * on a CSS-drawn chart with no PDF exporter gets the CSV link and nothing else,
51
+ * rather than three buttons of which two apologise.
52
+ */
53
+ export function useAvailableEmbedActions(actions, target) {
54
+ const requested = resolveEmbedActions(actions);
55
+ const png = useHasExportableSvg(target);
56
+ const pdf = usePdfExport(target);
57
+ return requested.filter((action) => {
58
+ if (action === 'png')
59
+ return png;
60
+ if (action === 'pdf')
61
+ return pdf.available;
62
+ return true;
63
+ });
64
+ }
@@ -0,0 +1,20 @@
1
+ import { type EmbedActions } from './actions';
2
+ import type { EmbeddedChartPayload } from './payload';
3
+ /**
4
+ * One embedded chart, drawn from a payload that has already arrived.
5
+ *
6
+ * Internal on purpose: `<EmbeddedChart>` fetches one, `<EmbeddedDashboard>`
7
+ * gets several in a single response, and both draw them through here so a chart
8
+ * looks the same whichever way it got to the page.
9
+ *
10
+ * The body is `ChartBody` — the same component the console's cards use, not a
11
+ * second copy of it. That is the point of the extraction: a bar chart in a
12
+ * host's application and the same bar chart in the console are the same
13
+ * drawing, and stay that way when either changes.
14
+ */
15
+ export declare function EmbeddedChartCard({ chart, actions, height, className, }: {
16
+ chart: EmbeddedChartPayload;
17
+ actions?: EmbedActions;
18
+ height?: number;
19
+ className?: string;
20
+ }): import("react/jsx-runtime").JSX.Element;
@@ -0,0 +1,89 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ import { Download, FileDown, ImageDown } from 'lucide-react';
3
+ import { useRef } from 'react';
4
+ import { ChartBody } from '../charts/body';
5
+ import { cn } from '../cn';
6
+ import { useCatalogClient } from '../context';
7
+ import { usePdfExport } from '../export/use-pdf-export';
8
+ import { usePngExport } from '../export/use-png-export';
9
+ import { useAvailableEmbedActions } from './actions';
10
+ import { resultFromEmbed } from './payload';
11
+ const MUTED = 'text-zinc-400 dark:text-zinc-500';
12
+ /**
13
+ * One embedded chart, drawn from a payload that has already arrived.
14
+ *
15
+ * Internal on purpose: `<EmbeddedChart>` fetches one, `<EmbeddedDashboard>`
16
+ * gets several in a single response, and both draw them through here so a chart
17
+ * looks the same whichever way it got to the page.
18
+ *
19
+ * The body is `ChartBody` — the same component the console's cards use, not a
20
+ * second copy of it. That is the point of the extraction: a bar chart in a
21
+ * host's application and the same bar chart in the console are the same
22
+ * drawing, and stay that way when either changes.
23
+ */
24
+ export function EmbeddedChartCard({ chart, actions, height = 200, className, }) {
25
+ const chartRef = useRef(null);
26
+ return (_jsxs("div", { className: cn('min-w-0', className), children: [_jsxs("div", { className: "flex items-start justify-between gap-2", children: [_jsxs("div", { className: "min-w-0 flex-1", children: [_jsx("h3", { className: "truncate text-sm font-medium", children: chart.title }), _jsxs("time", { className: cn('font-mono text-[10px]', MUTED), dateTime: chart.generatedAt, children: [chart.rowCount, " rows", chart.cached ? ' · cached' : ''] })] }), _jsx(EmbedToolbar, { chartId: chart.id, actions: actions, chart: chartRef, title: chart.title })] }), chart.description && (_jsx("p", { className: cn('mt-0.5 truncate text-[11px]', MUTED), children: chart.description })), _jsx("div", { className: "mt-3", ref: chartRef, children: _jsx(ChartBody, { result: resultFromEmbed(chart), visualization: chart.visualization, height: height }) })] }));
27
+ }
28
+ /**
29
+ * The controls in an embedded chart's top-right.
30
+ *
31
+ * Output only, and empty by default — see `actions.ts` for why an embed carries
32
+ * no refresh, no delete, no width and no library picker. There is no branch
33
+ * here that can produce one: the toolbar can only draw what
34
+ * `resolveEmbedActions` returns, and that can only return members of
35
+ * `EMBED_ACTIONS`.
36
+ *
37
+ * No `Tooltip`, unlike the console's card. Tooltips here need a
38
+ * `TooltipProvider` above them, and an embed is mounted wherever the host
39
+ * pleases — a missing provider would be a crash in somebody else's page. A
40
+ * `title` plus an `aria-label` needs no context and is what a screen reader
41
+ * reads anyway.
42
+ */
43
+ function EmbedToolbar({ chartId, actions, chart, title, }) {
44
+ // Availability, not just what was asked for. A PNG needs an `<svg>` — the
45
+ // built-in renderer draws divs — and a PDF needs the host to have registered
46
+ // an exporter. Filtering here is what lets `EmbedActionControl` keep an
47
+ // exhaustive switch: everything it is handed is drawable.
48
+ const available = useAvailableEmbedActions(actions, chart);
49
+ if (available.length === 0)
50
+ return null;
51
+ return (_jsx("div", { className: "flex shrink-0 items-center gap-0.5", children: available.map((action) => (_jsx(EmbedActionControl, { action: action, chartId: chartId, chart: chart, title: title }, action))) }));
52
+ }
53
+ const CONTROL = 'rounded-sm p-1 hover:bg-zinc-100 dark:hover:bg-zinc-800';
54
+ /**
55
+ * One action, drawn.
56
+ *
57
+ * The `never` at the bottom is the point of the shape: adding a member to
58
+ * {@link EmbedAction} without drawing it here stops compiling. The alternative
59
+ * — a fallthrough returning null — is exactly the "an option that does nothing"
60
+ * failure the union was written to prevent, just moved one level down.
61
+ *
62
+ * Every action handed here is already known to be performable —
63
+ * `useAvailableEmbedActions` filtered on that — so no branch needs to ask
64
+ * whether it can do its job. That separation is what keeps this switch
65
+ * exhaustive AND honest at the same time.
66
+ */
67
+ function EmbedActionControl({ action, chartId, chart, title, }) {
68
+ const client = useCatalogClient();
69
+ // The chart's own title as the filename, rather than the timestamped default:
70
+ // somebody exporting three cards from one board wants three names they can
71
+ // tell apart afterwards.
72
+ const png = usePngExport({ filename: () => `${title}.png` });
73
+ const pdf = usePdfExport(chart, { title });
74
+ if (action === 'csv') {
75
+ // A link, not a button, because the server's export is a GET that streams
76
+ // a file — the browser downloads it without this component touching the
77
+ // response, and a link can be middle-clicked, copied, or handed to a
78
+ // host's own download manager.
79
+ return (_jsx("a", { href: client.exportUrl(chartId), "aria-label": "Download CSV", title: "Download CSV", className: cn(CONTROL, MUTED), children: _jsx(Download, { size: 11 }) }));
80
+ }
81
+ if (action === 'png') {
82
+ return (_jsx("button", { type: "button", onClick: () => png.exportPng(chart), disabled: png.exporting, "aria-label": "Download PNG", title: "Download PNG", className: cn(CONTROL, MUTED), children: _jsx(ImageDown, { size: 11 }) }));
83
+ }
84
+ if (action === 'pdf') {
85
+ return (_jsx("button", { type: "button", onClick: () => pdf.exportPdf(), disabled: pdf.exporting, "aria-label": pdf.label ?? 'Download PDF', title: pdf.label ?? 'Download PDF', className: cn(CONTROL, MUTED), children: _jsx(FileDown, { size: 11 }) }));
86
+ }
87
+ const undrawn = action;
88
+ return undrawn;
89
+ }
@@ -0,0 +1,12 @@
1
+ /**
2
+ * Embedding: a chart or a whole board, in an application that is not this one.
3
+ *
4
+ * The console's screens and these components read the same data and share the
5
+ * same drawing code (`charts/body.tsx`), and differ in exactly one way: nothing
6
+ * here can change anything. See `actions.ts` for what that rules out and why.
7
+ */
8
+ export { EMBED_ACTIONS, type EmbedAction, type EmbedActions, resolveEmbedActions, } from './actions';
9
+ export { EmbeddedChart, type EmbeddedChartProps } from './EmbeddedChart';
10
+ export { EmbeddedDashboard, type EmbeddedDashboardProps } from './EmbeddedDashboard';
11
+ export { chartsInLayoutOrder, type EmbeddedChartPayload, type EmbeddedDashboardPayload, } from './payload';
12
+ export type { EmbedFailureSlot, EmbedLoadingSlot } from './slots';
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Embedding: a chart or a whole board, in an application that is not this one.
3
+ *
4
+ * The console's screens and these components read the same data and share the
5
+ * same drawing code (`charts/body.tsx`), and differ in exactly one way: nothing
6
+ * here can change anything. See `actions.ts` for what that rules out and why.
7
+ */
8
+ export { EMBED_ACTIONS, resolveEmbedActions, } from './actions';
9
+ export { EmbeddedChart } from './EmbeddedChart';
10
+ export { EmbeddedDashboard } from './EmbeddedDashboard';
11
+ export { chartsInLayoutOrder, } from './payload';