@dudousxd/nestjs-catalog-react 0.7.2 → 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 (49) hide show
  1. package/README.md +41 -5
  2. package/dist/DashboardBoard.d.ts +22 -0
  3. package/dist/DashboardBoard.js +134 -69
  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/charts/registry.d.ts +19 -0
  12. package/dist/charts/registry.js +22 -0
  13. package/dist/context.d.ts +71 -0
  14. package/dist/context.js +20 -3
  15. package/dist/embed/EmbeddedChart.d.ts +41 -0
  16. package/dist/embed/EmbeddedChart.js +25 -0
  17. package/dist/embed/EmbeddedDashboard.d.ts +32 -0
  18. package/dist/embed/EmbeddedDashboard.js +38 -0
  19. package/dist/embed/actions.d.ts +75 -0
  20. package/dist/embed/actions.js +64 -0
  21. package/dist/embed/chart-card.d.ts +20 -0
  22. package/dist/embed/chart-card.js +89 -0
  23. package/dist/embed/index.d.ts +12 -0
  24. package/dist/embed/index.js +11 -0
  25. package/dist/embed/payload.d.ts +78 -0
  26. package/dist/embed/payload.js +42 -0
  27. package/dist/embed/slots.d.ts +52 -0
  28. package/dist/embed/slots.js +44 -0
  29. package/dist/export/css-variables.d.ts +60 -0
  30. package/dist/export/css-variables.js +137 -0
  31. package/dist/export/index.d.ts +21 -0
  32. package/dist/export/index.js +21 -0
  33. package/dist/export/pdf.d.ts +136 -0
  34. package/dist/export/pdf.js +97 -0
  35. package/dist/export/png.d.ts +88 -0
  36. package/dist/export/png.js +125 -0
  37. package/dist/export/serialize.d.ts +92 -0
  38. package/dist/export/serialize.js +298 -0
  39. package/dist/export/use-pdf-export.d.ts +66 -0
  40. package/dist/export/use-pdf-export.js +63 -0
  41. package/dist/export/use-png-export.d.ts +82 -0
  42. package/dist/export/use-png-export.js +126 -0
  43. package/dist/index.d.ts +3 -1
  44. package/dist/index.js +21 -1
  45. package/dist/routes.d.ts +25 -1
  46. package/dist/routes.js +25 -1
  47. package/dist/sharing.d.ts +81 -0
  48. package/dist/sharing.js +72 -0
  49. package/package.json +2 -2
package/dist/index.js CHANGED
@@ -9,6 +9,9 @@ export { ChartEmpty, ChartFailed, ChartSkeleton, } from './charts/skeleton';
9
9
  // The fallback every other renderer degrades to, and the guard that decides
10
10
  // when a time-scale chart cannot draw what a saved query asked for.
11
11
  export { CssBarChart, looksLikeTimeSeries } from './charts/css';
12
+ // Embedding: the same charts, in an application that is not this one. Output
13
+ // only — see src/embed/actions.ts for what an embed deliberately cannot do.
14
+ export { EMBED_ACTIONS, EmbeddedChart, EmbeddedDashboard, chartsInLayoutOrder, resolveEmbedActions, } from './embed';
12
15
  export { FlowView } from './FlowView';
13
16
  export { GovernanceTimeline } from './GovernanceTimeline';
14
17
  export { QueryConsole } from './QueryConsole';
@@ -53,7 +56,10 @@ export { CatalogProvider, catalogQueryKeys, useCatalogClient, } from './context'
53
56
  // The paths behind the pipeline and access screens, exported so a host can
54
57
  // mount those endpoints wherever it likes and tell the provider where they are.
55
58
  // See routes.ts for why they are here rather than in the server package.
56
- export { accessRoutes, DEFAULT_ACCESS_BASE_PATH, DEFAULT_PIPELINE_BASE_PATH, pipelineRoutes, } from './routes';
59
+ export { accessRoutes, DEFAULT_ACCESS_BASE_PATH, DEFAULT_PIPELINE_BASE_PATH,
60
+ // The embed paths, which the catalog controller does serve — exported so a
61
+ // host writing its own embed consumer need not restate them. See routes.ts.
62
+ embedRoutes, pipelineRoutes, } from './routes';
57
63
  // The vendored primitives. Exported because a host composing its own screen out
58
64
  // of this package's parts should not have to rebuild a tooltip to match.
59
65
  export { ConfirmDialog } from './ui/dialog';
@@ -66,3 +72,17 @@ export { RichTextField, RichTextView, } from './ui/rich-text-field';
66
72
  export { Button } from './ui/button';
67
73
  export { Tabs, TabsList, TabsPanel, TabsTab } from './ui/tabs';
68
74
  export { Tooltip, TooltipProvider } from './ui/tooltip';
75
+ // Getting a chart out of the console as a file.
76
+ //
77
+ // PNG needs no dependency at all — a serialised SVG, a canvas and `toBlob` are
78
+ // already in every browser. Two limits are worth knowing before offering it: an
79
+ // SVG rasterised through a data URI cannot load `@font-face`, so exported text
80
+ // falls back to a system face; and the built-in CSS bar chart draws with divs
81
+ // rather than an `<svg>`, so it cannot be exported at all.
82
+ //
83
+ // PDF is a SEAM, not a renderer. This package takes no PDF dependency — the
84
+ // two candidates cost ~128KB gzipped on every consumer for a feature only some
85
+ // want, which is the same argument `charts/registry.tsx` makes about chart
86
+ // libraries. The host registers something backed by its own document pipeline,
87
+ // and where nobody did, no PDF action appears.
88
+ export { buildChartPdfSource, canRasterise, defaultPngFilename, downloadSvgAsPng, exportSvgAsPdf, findExportableSvg, getPdfExporter, rasteriseSerializedSvg, registerPdfExporter, serializeSvg, subscribeToPdfExporter, svgToPngBlob, useHasExportableSvg, usePdfExport, usePngExport, } from './export';
package/dist/routes.d.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  /**
2
- * The paths behind the pipeline and access screens.
2
+ * The paths behind the pipeline and access screens — and, for now, the embed
3
+ * components, which are the documented exception at the top of the file.
3
4
  *
4
5
  * These deliberately do **not** live in `@dudousxd/nestjs-catalog/client` beside
5
6
  * `catalogRoutes`, and the difference is worth being precise about, because it
@@ -29,6 +30,29 @@
29
30
  * `CatalogClient` plus these paths, and a host that would rather satisfy it from
30
31
  * somewhere else entirely can pass its own base path, or replace the client.
31
32
  */
33
+ /**
34
+ * The embed API, which is the exception to everything above.
35
+ *
36
+ * These paths ARE served by the catalog library's own controller — `GET
37
+ * embed`, `GET embed/charts/:id`, `GET embed/dashboards/:id`, behind
38
+ * `catalog:embed` — so by the argument in this file's header they belong beside
39
+ * `catalogRoutes` in `@dudousxd/nestjs-catalog/client`, and that is where they
40
+ * should end up. They are here only because the embed components landed in this
41
+ * package first; moving them is a one-line change in the server package and a
42
+ * re-export here.
43
+ *
44
+ * Which is why they are a frozen object of builders, in `catalogRoutes`' style,
45
+ * rather than a `f(basePath)` like `pipelineRoutes` below. The shape is a
46
+ * statement about who owns the path: a host cannot move these anywhere the rest
47
+ * of the catalog controller has not also moved, so offering a base path would
48
+ * be offering a knob that cannot be turned independently.
49
+ */
50
+ export declare const embedRoutes: {
51
+ /** What this caller may embed. Discovery, so ids need not be passed out of band. */
52
+ readonly embeddable: () => string;
53
+ readonly chart: (id: string) => string;
54
+ readonly dashboard: (id: string) => string;
55
+ };
32
56
  /** Where the pipeline endpoints sit unless the host says otherwise. */
33
57
  export declare const DEFAULT_PIPELINE_BASE_PATH = "/pipeline";
34
58
  /** Where the access endpoints sit unless the host says otherwise. */
package/dist/routes.js CHANGED
@@ -1,5 +1,6 @@
1
1
  /**
2
- * The paths behind the pipeline and access screens.
2
+ * The paths behind the pipeline and access screens — and, for now, the embed
3
+ * components, which are the documented exception at the top of the file.
3
4
  *
4
5
  * These deliberately do **not** live in `@dudousxd/nestjs-catalog/client` beside
5
6
  * `catalogRoutes`, and the difference is worth being precise about, because it
@@ -29,6 +30,29 @@
29
30
  * `CatalogClient` plus these paths, and a host that would rather satisfy it from
30
31
  * somewhere else entirely can pass its own base path, or replace the client.
31
32
  */
33
+ /**
34
+ * The embed API, which is the exception to everything above.
35
+ *
36
+ * These paths ARE served by the catalog library's own controller — `GET
37
+ * embed`, `GET embed/charts/:id`, `GET embed/dashboards/:id`, behind
38
+ * `catalog:embed` — so by the argument in this file's header they belong beside
39
+ * `catalogRoutes` in `@dudousxd/nestjs-catalog/client`, and that is where they
40
+ * should end up. They are here only because the embed components landed in this
41
+ * package first; moving them is a one-line change in the server package and a
42
+ * re-export here.
43
+ *
44
+ * Which is why they are a frozen object of builders, in `catalogRoutes`' style,
45
+ * rather than a `f(basePath)` like `pipelineRoutes` below. The shape is a
46
+ * statement about who owns the path: a host cannot move these anywhere the rest
47
+ * of the catalog controller has not also moved, so offering a base path would
48
+ * be offering a knob that cannot be turned independently.
49
+ */
50
+ export const embedRoutes = {
51
+ /** What this caller may embed. Discovery, so ids need not be passed out of band. */
52
+ embeddable: () => '/catalog/embed',
53
+ chart: (id) => `/catalog/embed/charts/${encodeURIComponent(id)}`,
54
+ dashboard: (id) => `/catalog/embed/dashboards/${encodeURIComponent(id)}`,
55
+ };
32
56
  /** Where the pipeline endpoints sit unless the host says otherwise. */
33
57
  export const DEFAULT_PIPELINE_BASE_PATH = '/pipeline';
34
58
  /** Where the access endpoints sit unless the host says otherwise. */
@@ -0,0 +1,81 @@
1
+ /**
2
+ * Handing something to an application this catalog does not own.
3
+ *
4
+ * The copy and the control live together, in one module, because there are two
5
+ * surfaces that perform this act — a dashboard's header and a saved query's row
6
+ * — and the sentence describing what sharing MEANS has to be the same sentence
7
+ * in both. Two hand-written versions drift, and the one that drifts is the one
8
+ * somebody read before clicking.
9
+ *
10
+ * WHY THIS IS NOT A SWITCH
11
+ * ------------------------
12
+ * `ui/switch.tsx` exists and would have been one line. It is the wrong control
13
+ * here, for a reason that is specific rather than aesthetic: a switch says
14
+ * "setting", flips on a single click, and distinguishes its two states by the
15
+ * position of a knob. `shared` is not a setting — it is the entire access
16
+ * boundary of the embed API, and the server treats crossing it as an event
17
+ * worth recording, in both directions and including by deletion (see the
18
+ * sharing block in `catalog.service.ts`). A control for an audited act should
19
+ * state where you are before it offers to move you: the badge is the state, the
20
+ * sentence is what the state means for whoever else can reach this, and the
21
+ * button names the transition rather than merely inverting a boolean.
22
+ *
23
+ * Both directions, everywhere. `shared` used to be settable only when a query
24
+ * was first saved, which made a mistaken share a one-way door — the flag was
25
+ * reachable from no screen afterwards, so the only way back was deleting the
26
+ * query. A grant you cannot revoke from the console is worse than one you
27
+ * cannot make there.
28
+ */
29
+ export type ShareableKind = 'dashboard' | 'query';
30
+ /**
31
+ * What the current state means, in the terms the server enforces it in.
32
+ *
33
+ * Named scopes rather than "other apps", because `catalog:embed` is the actual
34
+ * boundary and it is what an operator would have to go and look at. "Other
35
+ * apps" reads as "apps you have already integrated"; the truth is anything
36
+ * holding that scope, which may be more than the person clicking has in mind.
37
+ */
38
+ export declare function shareStatement(kind: ShareableKind, shared: boolean): string;
39
+ /** The transition, as a verb phrase. The button's whole job is to name it. */
40
+ export declare function shareActionLabel(kind: ShareableKind, shared: boolean): string;
41
+ /**
42
+ * The state, at a glance.
43
+ *
44
+ * Rendered even when private, in the panel layout: "no badge" would leave the
45
+ * reader deducing the state from the absence of a mark, and a board nobody
46
+ * shared and a board whose state has not loaded look identical that way. In a
47
+ * dense list the private badge is dropped — see {@link ShareControl} — because
48
+ * there the absence is the common case rather than an answer.
49
+ */
50
+ export declare function ShareBadge({ shared, className }: {
51
+ shared: boolean;
52
+ className?: string;
53
+ }): import("react/jsx-runtime").JSX.Element;
54
+ export interface ShareControlProps {
55
+ kind: ShareableKind;
56
+ shared: boolean;
57
+ /** Performs the transition. The control never assumes it succeeded. */
58
+ onChange: (shared: boolean) => void;
59
+ /** In flight. Disables the button rather than hiding it, so the row stays put. */
60
+ pending?: boolean;
61
+ /**
62
+ * A refusal, shown beside the control.
63
+ *
64
+ * Sharing is the one action in this console whose failure is invisible from
65
+ * its own result: the board looks the same, and the person walks away
66
+ * believing an outside application can now reach it. So a rejected write says
67
+ * so here rather than only in the network tab.
68
+ */
69
+ error?: unknown;
70
+ /** Names the thing, for the accessible label of a control in a list of them. */
71
+ name?: string;
72
+ /**
73
+ * `'panel'` — badge, sentence and button on one bordered row, for a screen
74
+ * with room for it. `'row'` — the button alone, for a dense list where the
75
+ * badge is rendered separately beside the item's name and the sentence
76
+ * arrives as the button's `title`.
77
+ */
78
+ layout?: 'panel' | 'row';
79
+ className?: string;
80
+ }
81
+ export declare function ShareControl({ kind, shared, onChange, pending, error, name, layout, className, }: ShareControlProps): import("react/jsx-runtime").JSX.Element;
@@ -0,0 +1,72 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
+ import { Lock, Share2 } from 'lucide-react';
3
+ import { cn } from './cn';
4
+ import { Button } from './ui/button';
5
+ const MUTED = 'text-zinc-400 dark:text-zinc-500';
6
+ const RULE = 'border-zinc-200 dark:border-zinc-800';
7
+ /**
8
+ * What the current state means, in the terms the server enforces it in.
9
+ *
10
+ * Named scopes rather than "other apps", because `catalog:embed` is the actual
11
+ * boundary and it is what an operator would have to go and look at. "Other
12
+ * apps" reads as "apps you have already integrated"; the truth is anything
13
+ * holding that scope, which may be more than the person clicking has in mind.
14
+ */
15
+ export function shareStatement(kind, shared) {
16
+ if (kind === 'dashboard') {
17
+ return shared
18
+ ? 'Shared — any application with catalog:embed can fetch this board, and every shared query on it.'
19
+ : 'Private — the embed API refuses this board. It exists only inside this console.';
20
+ }
21
+ return shared
22
+ ? 'Shared — any application with catalog:embed can fetch these rows, here or as a card on a shared board.'
23
+ : 'Private — the embed API refuses this query, and a card built on it is left out of a shared board.';
24
+ }
25
+ /** The transition, as a verb phrase. The button's whole job is to name it. */
26
+ export function shareActionLabel(kind, shared) {
27
+ return shared ? `Stop sharing this ${kind}` : `Share this ${kind}`;
28
+ }
29
+ /**
30
+ * The state, at a glance.
31
+ *
32
+ * Rendered even when private, in the panel layout: "no badge" would leave the
33
+ * reader deducing the state from the absence of a mark, and a board nobody
34
+ * shared and a board whose state has not loaded look identical that way. In a
35
+ * dense list the private badge is dropped — see {@link ShareControl} — because
36
+ * there the absence is the common case rather than an answer.
37
+ */
38
+ export function ShareBadge({ shared, className }) {
39
+ return (_jsxs("span", { className: cn('inline-flex shrink-0 items-center gap-1 rounded-md px-1.5 py-0.5', 'font-mono text-[10px] uppercase tracking-[0.12em]', shared
40
+ ? 'bg-sky-100 text-sky-700 dark:bg-sky-950 dark:text-sky-300'
41
+ : cn('border', RULE, MUTED), className), children: [shared ? _jsx(Share2, { size: 10 }) : _jsx(Lock, { size: 10 }), shared ? 'Shared' : 'Private'] }));
42
+ }
43
+ function errorMessage(error) {
44
+ return error instanceof Error ? error.message : 'The change was refused.';
45
+ }
46
+ export function ShareControl({ kind, shared, onChange, pending = false, error, name, layout = 'panel', className, }) {
47
+ const statement = shareStatement(kind, shared);
48
+ const action = shareActionLabel(kind, shared);
49
+ // The label carries the item's name in a list, because a screen reader
50
+ // reaching the fourth "Stop sharing this query" of a list has been told
51
+ // nothing about which query it would stop sharing.
52
+ const label = name ? `${action}: ${name}` : action;
53
+ if (layout === 'row') {
54
+ return (_jsx(Button, { variant: "ghost", size: "sm", onClick: () => onChange(!shared), disabled: pending, "aria-label": label,
55
+ // Both, and they say different things: the accessible name is the
56
+ // ACTION, the title is the CONSEQUENCE. A tooltip is deliberately not
57
+ // used — `ui/tooltip` needs a provider above it, and this panel is
58
+ // mounted by hosts that may not have one.
59
+ title: `${statement} ${action}.`, className: cn('px-1.5 font-mono text-[10px] uppercase tracking-[0.12em]', className), children: shared ? 'Unshare' : 'Share' }));
60
+ }
61
+ return (_jsxs("div", { className: cn('flex flex-col gap-1', className), children: [_jsxs("div", { className: cn('flex items-center gap-3 rounded-lg border px-3 py-2', RULE), children: [_jsx(ShareBadge, { shared: shared }), _jsx("p", { className: cn('min-w-0 flex-1 text-[11px]', MUTED), children: statement }), _jsx(Button
62
+ // Sharing is the louder half of the pair, so it is the accented
63
+ // button and un-sharing is the quiet one. Neither is destructive:
64
+ // `destructive` is reserved for what cannot be undone, and both of
65
+ // these are one click from being undone.
66
+ , {
67
+ // Sharing is the louder half of the pair, so it is the accented
68
+ // button and un-sharing is the quiet one. Neither is destructive:
69
+ // `destructive` is reserved for what cannot be undone, and both of
70
+ // these are one click from being undone.
71
+ variant: shared ? 'outline' : 'default', size: "sm", onClick: () => onChange(!shared), disabled: pending, "aria-label": label, children: action })] }), error !== undefined && error !== null && (_jsx("p", { className: "text-[11px] text-red-600", children: errorMessage(error) }))] }));
72
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dudousxd/nestjs-catalog-react",
3
- "version": "0.7.2",
3
+ "version": "0.9.0",
4
4
  "description": "Ready-made React screens for @dudousxd/nestjs-catalog — a model manager and a generic object explorer you can drop into your own app shell.",
5
5
  "license": "MIT",
6
6
  "author": "Davide Carvalho",
@@ -106,7 +106,7 @@
106
106
  "@tiptap/pm": "3.29.2",
107
107
  "tiptap-markdown": "0.9.0",
108
108
  "@tiptap/core": "3.29.2",
109
- "@dudousxd/nestjs-catalog": "0.4.1"
109
+ "@dudousxd/nestjs-catalog": "0.6.0"
110
110
  },
111
111
  "dependencies": {
112
112
  "clsx": "2.1.1",