@dudousxd/nestjs-catalog-react 0.8.0 → 0.10.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 (53) hide show
  1. package/README.md +41 -5
  2. package/dist/CatalogManager.js +104 -5
  3. package/dist/DashboardBoard.d.ts +22 -0
  4. package/dist/DashboardBoard.js +88 -67
  5. package/dist/FlowView.js +47 -4
  6. package/dist/GovernanceTimeline.js +11 -1
  7. package/dist/PipelineConsole.d.ts +124 -1
  8. package/dist/PipelineConsole.js +188 -7
  9. package/dist/SavedQueryPanel.d.ts +0 -8
  10. package/dist/SavedQueryPanel.js +48 -9
  11. package/dist/charts/body.d.ts +39 -0
  12. package/dist/charts/body.js +53 -0
  13. package/dist/charts/grid.d.ts +23 -0
  14. package/dist/charts/grid.js +39 -0
  15. package/dist/context.d.ts +112 -1
  16. package/dist/context.js +31 -5
  17. package/dist/embed/EmbeddedChart.d.ts +41 -0
  18. package/dist/embed/EmbeddedChart.js +25 -0
  19. package/dist/embed/EmbeddedDashboard.d.ts +32 -0
  20. package/dist/embed/EmbeddedDashboard.js +38 -0
  21. package/dist/embed/actions.d.ts +75 -0
  22. package/dist/embed/actions.js +64 -0
  23. package/dist/embed/chart-card.d.ts +20 -0
  24. package/dist/embed/chart-card.js +89 -0
  25. package/dist/embed/index.d.ts +12 -0
  26. package/dist/embed/index.js +11 -0
  27. package/dist/embed/payload.d.ts +78 -0
  28. package/dist/embed/payload.js +42 -0
  29. package/dist/embed/slots.d.ts +52 -0
  30. package/dist/embed/slots.js +44 -0
  31. package/dist/export/css-variables.d.ts +60 -0
  32. package/dist/export/css-variables.js +137 -0
  33. package/dist/export/index.d.ts +21 -0
  34. package/dist/export/index.js +21 -0
  35. package/dist/export/pdf.d.ts +136 -0
  36. package/dist/export/pdf.js +97 -0
  37. package/dist/export/png.d.ts +88 -0
  38. package/dist/export/png.js +125 -0
  39. package/dist/export/serialize.d.ts +92 -0
  40. package/dist/export/serialize.js +298 -0
  41. package/dist/export/use-pdf-export.d.ts +66 -0
  42. package/dist/export/use-pdf-export.js +63 -0
  43. package/dist/export/use-png-export.d.ts +82 -0
  44. package/dist/export/use-png-export.js +126 -0
  45. package/dist/freshness.d.ts +37 -0
  46. package/dist/freshness.js +44 -0
  47. package/dist/index.d.ts +3 -1
  48. package/dist/index.js +21 -1
  49. package/dist/routes.d.ts +47 -1
  50. package/dist/routes.js +37 -1
  51. package/dist/sharing.d.ts +81 -0
  52. package/dist/sharing.js +72 -0
  53. package/package.json +2 -2
@@ -0,0 +1,53 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ import { useMemo } from 'react';
3
+ import { DataTable, renderUnknown } from '../ui/data-table';
4
+ import { CssBarChart } from './css';
5
+ import { getChartRenderer } from './registry';
6
+ import { ChartEmpty } from './skeleton';
7
+ export function ChartBody({ result, visualization, height = 200, maxColumns, maxRows, }) {
8
+ // Held at the chart's own height rather than collapsing to one line, so a
9
+ // card that matched nothing does not resize the grid around it — and said in
10
+ // words, because "no rows" beside a skeleton-shaped hole is the one reading
11
+ // that must never be ambiguous.
12
+ if (result.rowCount === 0) {
13
+ return _jsx(ChartEmpty, { height: height, message: "The query ran and matched nothing." });
14
+ }
15
+ if (visualization.kind === 'number') {
16
+ const column = visualization.valueColumns?.[0] ?? result.columns[0];
17
+ return (_jsxs("div", { className: "py-4 text-center", children: [_jsx("div", { className: "font-mono text-3xl tabular-nums", children: String(result.rows[0]?.[column] ?? '—') }), _jsx("div", { className: "mt-1 font-mono text-[10px] uppercase text-zinc-400 dark:text-zinc-500", children: visualization.labelColumn ?? column })] }));
18
+ }
19
+ if (visualization.kind === 'bar' ||
20
+ visualization.kind === 'line' ||
21
+ visualization.kind === 'area') {
22
+ // A registered library when the query names one and the host installed it;
23
+ // otherwise the built-in bars. Falling back beats failing: a dashboard
24
+ // should degrade to a plainer chart, not to an error message.
25
+ const Renderer = getChartRenderer(visualization.library);
26
+ if (Renderer) {
27
+ return _jsx(Renderer, { result: result, visualization: visualization, height: height });
28
+ }
29
+ return _jsx(CssBarChart, { result: result, visualization: visualization, height: height });
30
+ }
31
+ return _jsx(ChartTable, { result: result, maxColumns: maxColumns, maxRows: maxRows });
32
+ }
33
+ /**
34
+ * The table rendering, in its own component so `ChartBody` above can early-return.
35
+ *
36
+ * Hooks cannot follow a conditional return, and every branch of a chart body is
37
+ * a conditional return.
38
+ */
39
+ function ChartTable({ result, maxColumns, maxRows, }) {
40
+ const shown = useMemo(() => (maxColumns === undefined ? result.columns : result.columns.slice(0, maxColumns)), [result.columns, maxColumns]);
41
+ const columns = useMemo(() => shown.map((column) => ({
42
+ id: column,
43
+ accessorFn: (row) => row[column],
44
+ header: column,
45
+ cell: (context) => renderUnknown(context.getValue()),
46
+ })), [shown]);
47
+ const rows = useMemo(() => (maxRows === undefined ? result.rows : result.rows.slice(0, maxRows)), [result.rows, maxRows]);
48
+ const numericColumns = useMemo(() => {
49
+ const first = rows[0];
50
+ return new Set(first ? shown.filter((column) => typeof first[column] === 'number') : []);
51
+ }, [rows, shown]);
52
+ return (_jsx(DataTable, { data: rows, columns: columns, numeric: (id) => numericColumns.has(id), density: "text-[11px]" }));
53
+ }
@@ -0,0 +1,23 @@
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 declare const CHART_GRID = "grid grid-cols-1 gap-4 @2xl:grid-cols-2 @5xl:grid-cols-4";
18
+ /**
19
+ * Half the board is the default for a width nobody set or one nothing can
20
+ * honour — a stored card is JSON, so `width` arrives as whatever was written,
21
+ * and a missing class would silently collapse the card to one column.
22
+ */
23
+ export declare function chartSpan(width: number | undefined): string;
@@ -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,44 @@ 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;
42
+ /**
43
+ * `PUT`, for the one route that has to be one.
44
+ *
45
+ * Optional for the same reason `url` is: a transport written before this
46
+ * existed keeps compiling. Publishing a type is an idempotent upsert of the
47
+ * whole shape — the same body twice is the same result — and the publish
48
+ * route says so with its method. Adding a `POST` alias to spare this
49
+ * three-line addition would have put a second name on one act, and the two
50
+ * would eventually mean different things.
51
+ *
52
+ * A client that needs it and does not find it refuses by name rather than
53
+ * silently doing nothing, because a "Create type" button that returns without
54
+ * creating a type is the failure this whole panel exists to prevent.
55
+ */
56
+ put?<T>(path: string, body: unknown): Promise<T>;
18
57
  }
19
58
  /**
20
59
  * What this deployment can actually execute.
@@ -201,18 +240,56 @@ export interface CatalogClient {
201
240
  }>;
202
241
  exportUrl(id: string): string;
203
242
  listDashboards(): Promise<Dashboard[]>;
243
+ /**
244
+ * `shared` is declared on both writes, and it is not decoration.
245
+ *
246
+ * The server's `patchDashboard` says why one layer down: a field a body type
247
+ * does not name is a field a host's whitelisting `ValidationPipe` deletes, so
248
+ * the write appears to succeed and the flag never moves. This type dropped it
249
+ * again — and a field a CLIENT type does not name cannot even be passed, so
250
+ * the failure arrives earlier and reads as a compile error in the one screen
251
+ * that would have set it.
252
+ *
253
+ * What that cost: `shared` is the entire access boundary of the embed API, so
254
+ * every dashboard a shipped console produced was un-embeddable, `embedDashboard`
255
+ * answered `403` for all of them, and `<EmbeddedDashboard>`'s "Nothing on this
256
+ * dashboard has been shared" was not an empty state but the only state.
257
+ *
258
+ * On `saveDashboard` too, although the console's create form does not offer
259
+ * it — a board is created empty and there is nothing yet to share. The field
260
+ * is here because the route accepts it and a host driving this client
261
+ * directly should not have to discover that the two writes disagree.
262
+ */
204
263
  saveDashboard(input: {
205
264
  name: string;
206
265
  description?: string;
266
+ shared?: boolean;
207
267
  }): Promise<Dashboard>;
208
268
  updateDashboard(id: string, input: Partial<{
209
269
  name: string;
210
270
  description: string;
211
271
  cards: DashboardCard[];
272
+ shared: boolean;
212
273
  }>): Promise<Dashboard>;
213
274
  deleteDashboard(id: string): Promise<{
214
275
  deleted: boolean;
215
276
  }>;
277
+ /**
278
+ * What another application may render.
279
+ *
280
+ * Reads only, and rendered rather than executable: a chart comes back as
281
+ * columns and rows with a visualization, never as SQL, so an embed cannot ask
282
+ * for anything the sharer did not already share. Both refuse anything not
283
+ * explicitly marked shared in the console, which is why there is no
284
+ * `embedQuery(sql)` and never will be.
285
+ *
286
+ * `exportUrl` above is what an embedded chart's CSV action links to — the
287
+ * same export the console uses, because it is the same saved query, and
288
+ * resolved through the transport so it points at wherever the HOST mounted
289
+ * this catalog rather than at wherever the console happens to live.
290
+ */
291
+ embedChart(id: string): Promise<EmbeddedChartPayload>;
292
+ embedDashboard(id: string): Promise<EmbeddedDashboardPayload>;
216
293
  listEvents(query: {
217
294
  event?: string;
218
295
  typeName?: string;
@@ -259,6 +336,29 @@ export interface CatalogClient {
259
336
  deleted: boolean;
260
337
  }>;
261
338
  runConnector(id: string): Promise<ConnectorRun>;
339
+ /**
340
+ * What the source behind a connector looks like right now. Writes nothing.
341
+ *
342
+ * Typed loosely on purpose. The shape comes from
343
+ * `@dudousxd/nestjs-catalog-pipeline`, and this package must not import that
344
+ * one — it would drag a package built for a Node process, with database
345
+ * drivers behind optional imports, into a browser bundle. `PipelineCapabilities`
346
+ * above is mirrored for exactly the same reason.
347
+ */
348
+ discoverConnectorSchema(id: string): Promise<unknown>;
349
+ /**
350
+ * Publish an object type's schema — create it, or update the shape of one
351
+ * that exists.
352
+ *
353
+ * The only write on this client that does not go through the catalog's own
354
+ * routes: publishing is how a type comes into existence at all, and there is
355
+ * deliberately no `POST /catalog/types`, because structure follows a
356
+ * publisher and curation follows a person.
357
+ *
358
+ * Refuses by name when the transport cannot `PUT`, rather than resolving
359
+ * having done nothing.
360
+ */
361
+ publishType(name: string, schema: unknown): Promise<unknown>;
262
362
  listRuns(connectorId?: string): Promise<ConnectorRun[]>;
263
363
  listTransforms(): Promise<CatalogTransform[]>;
264
364
  saveTransform(input: TransformInput): Promise<CatalogTransform>;
@@ -327,11 +427,13 @@ export interface CatalogProviderProps {
327
427
  * the README passes nothing.
328
428
  */
329
429
  pipelineBasePath?: string;
430
+ /** Where `/publish` is mounted — a sibling of {@link pipelineBasePath}. */
431
+ publishBasePath?: string;
330
432
  /** Same, for the access endpoints. */
331
433
  accessBasePath?: string;
332
434
  children: ReactNode;
333
435
  }
334
- export declare function CatalogProvider({ transport, pipelineBasePath, accessBasePath, children, }: CatalogProviderProps): import("react/jsx-runtime").JSX.Element;
436
+ export declare function CatalogProvider({ transport, pipelineBasePath, publishBasePath, accessBasePath, children, }: CatalogProviderProps): import("react/jsx-runtime").JSX.Element;
335
437
  export declare function useCatalogClient(): CatalogClient;
336
438
  /** Query keys, exported so a host can invalidate them from its own code. */
337
439
  export declare const catalogQueryKeys: {
@@ -353,6 +455,15 @@ export declare const catalogQueryKeys: {
353
455
  transforms: readonly ["nestjs-catalog", "pipeline", "transforms"];
354
456
  runs: (connectorId?: string) => readonly ["nestjs-catalog", "pipeline", "runs", string];
355
457
  workflows: readonly ["nestjs-catalog", "pipeline", "workflows"];
458
+ /**
459
+ * The embed keys, under one prefix so a host can invalidate every embedded
460
+ * chart on its page at once — which is the only refresh an embed has. The
461
+ * components deliberately ship no refresh control of their own, so this is
462
+ * the seam a host uses to decide when its own page reloads its data.
463
+ */
464
+ embed: readonly ["nestjs-catalog", "embed"];
465
+ embeddedChart: (id: string) => readonly ["nestjs-catalog", "embed", "chart", string];
466
+ embeddedDashboard: (id: string) => readonly ["nestjs-catalog", "embed", "dashboard", string];
356
467
  access: readonly ["nestjs-catalog", "access"];
357
468
  principals: readonly ["nestjs-catalog", "access", "principals"];
358
469
  people: readonly ["nestjs-catalog", "access", "people"];
package/dist/context.js CHANGED
@@ -1,9 +1,9 @@
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, DEFAULT_PUBLISH_BASE_PATH, accessRoutes, embedRoutes, pipelineRoutes, } from './routes';
5
5
  const CatalogContext = createContext(null);
6
- export function CatalogProvider({ transport, pipelineBasePath = DEFAULT_PIPELINE_BASE_PATH, accessBasePath = DEFAULT_ACCESS_BASE_PATH, children, }) {
6
+ export function CatalogProvider({ transport, pipelineBasePath = DEFAULT_PIPELINE_BASE_PATH, publishBasePath = DEFAULT_PUBLISH_BASE_PATH, accessBasePath = DEFAULT_ACCESS_BASE_PATH, children, }) {
7
7
  const client = useMemo(() => {
8
8
  const pipeline = pipelineRoutes(pipelineBasePath);
9
9
  const access = accessRoutes(accessBasePath);
@@ -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()),
@@ -42,6 +50,15 @@ export function CatalogProvider({ transport, pipelineBasePath = DEFAULT_PIPELINE
42
50
  saveConnector: (input) => transport.post(pipeline.connectors(), input),
43
51
  deleteConnector: (id) => transport.delete(pipeline.connector(id)),
44
52
  runConnector: (id) => transport.post(pipeline.runConnector(id), {}),
53
+ discoverConnectorSchema: (id) => transport.post(pipeline.discoverConnectorSchema(id), {}),
54
+ publishType: (name, schema) => {
55
+ if (!transport.put) {
56
+ throw new Error('This transport cannot PUT, so it cannot publish a type. Implement `put` on the ' +
57
+ 'transport you passed to CatalogProvider — publishing is an idempotent upsert of ' +
58
+ 'the whole shape, which is why the route is a PUT and not a POST.');
59
+ }
60
+ return transport.put(`${publishBasePath}/${encodeURIComponent(name)}/schema`, schema);
61
+ },
45
62
  // The parameter is omitted rather than sent empty when no connector is
46
63
  // named, because a transport that serialises `connector=` turns "every
47
64
  // run" into "runs of the connector whose id is the empty string", which
@@ -59,7 +76,7 @@ export function CatalogProvider({ transport, pipelineBasePath = DEFAULT_PIPELINE
59
76
  listPeople: (query) => transport.get(access.people(query)),
60
77
  upsertPerson: (input) => transport.post(access.people(), input),
61
78
  };
62
- }, [transport, pipelineBasePath, accessBasePath]);
79
+ }, [transport, pipelineBasePath, publishBasePath, accessBasePath]);
63
80
  return _jsx(CatalogContext.Provider, { value: client, children: children });
64
81
  }
65
82
  export function useCatalogClient() {
@@ -89,6 +106,15 @@ export const catalogQueryKeys = {
89
106
  transforms: ['nestjs-catalog', 'pipeline', 'transforms'],
90
107
  runs: (connectorId) => ['nestjs-catalog', 'pipeline', 'runs', connectorId ?? 'all'],
91
108
  workflows: ['nestjs-catalog', 'pipeline', 'workflows'],
109
+ /**
110
+ * The embed keys, under one prefix so a host can invalidate every embedded
111
+ * chart on its page at once — which is the only refresh an embed has. The
112
+ * components deliberately ship no refresh control of their own, so this is
113
+ * the seam a host uses to decide when its own page reloads its data.
114
+ */
115
+ embed: ['nestjs-catalog', 'embed'],
116
+ embeddedChart: (id) => ['nestjs-catalog', 'embed', 'chart', id],
117
+ embeddedDashboard: (id) => ['nestjs-catalog', 'embed', 'dashboard', id],
92
118
  access: ['nestjs-catalog', 'access'],
93
119
  principals: ['nestjs-catalog', 'access', 'principals'],
94
120
  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
+ }