@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.
- package/README.md +41 -5
- package/dist/DashboardBoard.d.ts +22 -0
- package/dist/DashboardBoard.js +134 -69
- package/dist/GovernanceTimeline.js +11 -1
- package/dist/SavedQueryPanel.d.ts +0 -8
- package/dist/SavedQueryPanel.js +48 -9
- package/dist/charts/body.d.ts +39 -0
- package/dist/charts/body.js +53 -0
- package/dist/charts/grid.d.ts +23 -0
- package/dist/charts/grid.js +39 -0
- package/dist/charts/registry.d.ts +19 -0
- package/dist/charts/registry.js +22 -0
- package/dist/context.d.ts +71 -0
- package/dist/context.js +20 -3
- package/dist/embed/EmbeddedChart.d.ts +41 -0
- package/dist/embed/EmbeddedChart.js +25 -0
- package/dist/embed/EmbeddedDashboard.d.ts +32 -0
- package/dist/embed/EmbeddedDashboard.js +38 -0
- package/dist/embed/actions.d.ts +75 -0
- package/dist/embed/actions.js +64 -0
- package/dist/embed/chart-card.d.ts +20 -0
- package/dist/embed/chart-card.js +89 -0
- package/dist/embed/index.d.ts +12 -0
- package/dist/embed/index.js +11 -0
- package/dist/embed/payload.d.ts +78 -0
- package/dist/embed/payload.js +42 -0
- package/dist/embed/slots.d.ts +52 -0
- package/dist/embed/slots.js +44 -0
- package/dist/export/css-variables.d.ts +60 -0
- package/dist/export/css-variables.js +137 -0
- package/dist/export/index.d.ts +21 -0
- package/dist/export/index.js +21 -0
- package/dist/export/pdf.d.ts +136 -0
- package/dist/export/pdf.js +97 -0
- package/dist/export/png.d.ts +88 -0
- package/dist/export/png.js +125 -0
- package/dist/export/serialize.d.ts +92 -0
- package/dist/export/serialize.js +298 -0
- package/dist/export/use-pdf-export.d.ts +66 -0
- package/dist/export/use-pdf-export.js +63 -0
- package/dist/export/use-png-export.d.ts +82 -0
- package/dist/export/use-png-export.js +126 -0
- package/dist/index.d.ts +3 -1
- package/dist/index.js +21 -1
- package/dist/routes.d.ts +25 -1
- package/dist/routes.js +25 -1
- package/dist/sharing.d.ts +81 -0
- package/dist/sharing.js +72 -0
- package/package.json +2 -2
|
@@ -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';
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
import type { CatalogQueryResult, QueryVisualization } from '@dudousxd/nestjs-catalog/client';
|
|
2
|
+
/**
|
|
3
|
+
* What `GET /catalog/embed/charts/:id` answers.
|
|
4
|
+
*
|
|
5
|
+
* A rendered shape rather than SQL and a connection, and that is the whole
|
|
6
|
+
* point of the embed API: a consumer draws a chart without knowing this
|
|
7
|
+
* catalog's query language, without a database credential, and without being a
|
|
8
|
+
* second implementation of the console. It also means the server decides what
|
|
9
|
+
* the caller may see — an embed cannot widen its own access, because there is
|
|
10
|
+
* nothing to widen it with.
|
|
11
|
+
*
|
|
12
|
+
* DECLARED HERE, AND IT SHOULD NOT BE. The server owns these shapes — they are
|
|
13
|
+
* `EmbeddedChart` and `EmbeddedDashboard` in `catalog.workspace.ts` — but
|
|
14
|
+
* `@dudousxd/nestjs-catalog/client`, the browser entry point that exists
|
|
15
|
+
* precisely so a UI can have the response types, does not export them yet. The
|
|
16
|
+
* fix is one line in that package's `client.ts`; until it lands these are a
|
|
17
|
+
* mirror, and a mirror can drift. Anything reading a field not listed here is
|
|
18
|
+
* the signal that it has.
|
|
19
|
+
*
|
|
20
|
+
* The names differ from the server's by a suffix on purpose: `<EmbeddedChart>`
|
|
21
|
+
* in this package is the COMPONENT, and a type and a component that share a
|
|
22
|
+
* name is an import somebody eventually gets wrong.
|
|
23
|
+
*/
|
|
24
|
+
export interface EmbeddedChartPayload {
|
|
25
|
+
/** The saved query's id, which is also what the CSV export is keyed by. */
|
|
26
|
+
id: string;
|
|
27
|
+
title: string;
|
|
28
|
+
description?: string;
|
|
29
|
+
visualization: QueryVisualization;
|
|
30
|
+
/** Position and width from the dashboard, as a hint the consumer may ignore. */
|
|
31
|
+
layout?: {
|
|
32
|
+
width: number;
|
|
33
|
+
position: number;
|
|
34
|
+
};
|
|
35
|
+
columns: string[];
|
|
36
|
+
rows: Array<Record<string, unknown>>;
|
|
37
|
+
rowCount: number;
|
|
38
|
+
/** True when this came from cache; tells a consumer how fresh it is. */
|
|
39
|
+
cached: boolean;
|
|
40
|
+
generatedAt: string;
|
|
41
|
+
}
|
|
42
|
+
export interface EmbeddedDashboardPayload {
|
|
43
|
+
id: string;
|
|
44
|
+
name: string;
|
|
45
|
+
description?: string;
|
|
46
|
+
charts: EmbeddedChartPayload[];
|
|
47
|
+
generatedAt: string;
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* The embed payload, as the shared chart renderers want it.
|
|
51
|
+
*
|
|
52
|
+
* Two fields have to be supplied because `CatalogQueryResult` requires them and
|
|
53
|
+
* the embed payload does not carry them, so both are derived rather than
|
|
54
|
+
* invented where that is possible:
|
|
55
|
+
*
|
|
56
|
+
* - `truncated` is read off the payload itself. The server caps rows before it
|
|
57
|
+
* sends them but reports the full `rowCount`, so fewer rows than the count IS
|
|
58
|
+
* the truncation, and a renderer that says "showing all of it" when it is
|
|
59
|
+
* not is the class of quiet lie this project treats as its worst bug.
|
|
60
|
+
* - `elapsedMs` cannot be derived. The embed API deliberately says nothing
|
|
61
|
+
* about how long the query took — it may not have run at all, having come
|
|
62
|
+
* from cache — so this is 0, and no renderer should present it as a timing.
|
|
63
|
+
* `cached` and `generatedAt` are what actually answer "how fresh is this".
|
|
64
|
+
*/
|
|
65
|
+
export declare function resultFromEmbed(chart: EmbeddedChartPayload): CatalogQueryResult;
|
|
66
|
+
/**
|
|
67
|
+
* The charts of a dashboard, in the order its author laid them out.
|
|
68
|
+
*
|
|
69
|
+
* The server already sorts by position, so this is a second opinion — and it is
|
|
70
|
+
* worth having, because between the server and this component sits a host's
|
|
71
|
+
* HTTP client, possibly a proxy, possibly a cache, and a JSON array whose order
|
|
72
|
+
* survived all of them is an assumption rather than a guarantee. Getting it
|
|
73
|
+
* wrong is silent: the board simply reads wrong.
|
|
74
|
+
*
|
|
75
|
+
* A chart with no layout keeps its place at the end rather than jumping to the
|
|
76
|
+
* front, which is what `?? 0` would do to a payload that mixed the two.
|
|
77
|
+
*/
|
|
78
|
+
export declare function chartsInLayoutOrder(charts: EmbeddedChartPayload[]): EmbeddedChartPayload[];
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The embed payload, as the shared chart renderers want it.
|
|
3
|
+
*
|
|
4
|
+
* Two fields have to be supplied because `CatalogQueryResult` requires them and
|
|
5
|
+
* the embed payload does not carry them, so both are derived rather than
|
|
6
|
+
* invented where that is possible:
|
|
7
|
+
*
|
|
8
|
+
* - `truncated` is read off the payload itself. The server caps rows before it
|
|
9
|
+
* sends them but reports the full `rowCount`, so fewer rows than the count IS
|
|
10
|
+
* the truncation, and a renderer that says "showing all of it" when it is
|
|
11
|
+
* not is the class of quiet lie this project treats as its worst bug.
|
|
12
|
+
* - `elapsedMs` cannot be derived. The embed API deliberately says nothing
|
|
13
|
+
* about how long the query took — it may not have run at all, having come
|
|
14
|
+
* from cache — so this is 0, and no renderer should present it as a timing.
|
|
15
|
+
* `cached` and `generatedAt` are what actually answer "how fresh is this".
|
|
16
|
+
*/
|
|
17
|
+
export function resultFromEmbed(chart) {
|
|
18
|
+
return {
|
|
19
|
+
columns: chart.columns,
|
|
20
|
+
rows: chart.rows,
|
|
21
|
+
rowCount: chart.rowCount,
|
|
22
|
+
cached: chart.cached,
|
|
23
|
+
truncated: chart.rows.length < chart.rowCount,
|
|
24
|
+
elapsedMs: 0,
|
|
25
|
+
};
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* The charts of a dashboard, in the order its author laid them out.
|
|
29
|
+
*
|
|
30
|
+
* The server already sorts by position, so this is a second opinion — and it is
|
|
31
|
+
* worth having, because between the server and this component sits a host's
|
|
32
|
+
* HTTP client, possibly a proxy, possibly a cache, and a JSON array whose order
|
|
33
|
+
* survived all of them is an assumption rather than a guarantee. Getting it
|
|
34
|
+
* wrong is silent: the board simply reads wrong.
|
|
35
|
+
*
|
|
36
|
+
* A chart with no layout keeps its place at the end rather than jumping to the
|
|
37
|
+
* front, which is what `?? 0` would do to a payload that mixed the two.
|
|
38
|
+
*/
|
|
39
|
+
export function chartsInLayoutOrder(charts) {
|
|
40
|
+
return [...charts].sort((a, b) => (a.layout?.position ?? Number.POSITIVE_INFINITY) -
|
|
41
|
+
(b.layout?.position ?? Number.POSITIVE_INFINITY));
|
|
42
|
+
}
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
import type { ReactNode } from 'react';
|
|
2
|
+
/**
|
|
3
|
+
* What an embed shows while it is fetching, and what it shows when it could not.
|
|
4
|
+
*
|
|
5
|
+
* Both are the host's to decide, which is why they are props at all. A host's
|
|
6
|
+
* application already has a loading state — a shimmer, a spinner, a skeleton
|
|
7
|
+
* built to its own type scale — and a component that insists on its own is the
|
|
8
|
+
* one element on the page that looks like it came from somewhere else. The same
|
|
9
|
+
* goes double for failure: whether a chart that could not load should say so,
|
|
10
|
+
* disappear, or raise something to the host's error reporting is a product
|
|
11
|
+
* decision, and a library that answers it has answered it for everybody.
|
|
12
|
+
*
|
|
13
|
+
* A node OR a function. The node form is what most callers want and reads as
|
|
14
|
+
* markup; the function form exists because a failure has something to say (the
|
|
15
|
+
* error) and because a loading state may be expensive enough to be worth not
|
|
16
|
+
* constructing until it is needed.
|
|
17
|
+
*
|
|
18
|
+
* `undefined` — the prop not passed — falls back to the neutral defaults below.
|
|
19
|
+
* `null` does NOT: it is a host saying "render nothing here", and collapsing
|
|
20
|
+
* the two would leave no way to ask for silence.
|
|
21
|
+
*/
|
|
22
|
+
export type EmbedLoadingSlot = ReactNode | (() => ReactNode);
|
|
23
|
+
export type EmbedFailureSlot = ReactNode | ((error: Error) => ReactNode);
|
|
24
|
+
/**
|
|
25
|
+
* The default is empty space of the right height, not a spinner.
|
|
26
|
+
*
|
|
27
|
+
* It reserves exactly what the chart will occupy, so nothing on the host's page
|
|
28
|
+
* moves when the data lands, and it imposes no vocabulary of its own. A host
|
|
29
|
+
* that wants the package's own placeholder passes it: `loading={<ChartSkeleton
|
|
30
|
+
* kind="bar" />}`. This component cannot pick the kind for them — which chart
|
|
31
|
+
* is coming is in the payload that has not arrived yet.
|
|
32
|
+
*/
|
|
33
|
+
export declare function renderLoading(slot: EmbedLoadingSlot | undefined, height: number): ReactNode;
|
|
34
|
+
/**
|
|
35
|
+
* The default failure says what went wrong and offers NO retry.
|
|
36
|
+
*
|
|
37
|
+
* `ChartFailed` can draw a "Try again" button and deliberately is not given the
|
|
38
|
+
* handler that would: re-running is the console's affordance, and an embed that
|
|
39
|
+
* could re-run would let any page in any application re-execute the query at
|
|
40
|
+
* will, past whatever caching sits in front of it. A host that wants a retry
|
|
41
|
+
* has a better one than a button in someone else's component — it owns the
|
|
42
|
+
* query client, and can invalidate the key.
|
|
43
|
+
*/
|
|
44
|
+
export declare function renderFailure(slot: EmbedFailureSlot | undefined, error: Error, height: number): ReactNode;
|
|
45
|
+
/**
|
|
46
|
+
* React Query types its error as `Error`, but what a transport threw is
|
|
47
|
+
* whatever the host's HTTP client throws — a string, a response object, a
|
|
48
|
+
* rejection with no shape at all. Reading `.message` off that gives `undefined`
|
|
49
|
+
* and a component that reports an empty failure, which reads as a component
|
|
50
|
+
* that failed to render rather than a chart that failed to load.
|
|
51
|
+
*/
|
|
52
|
+
export declare function messageOf(error: unknown): string;
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import { jsx as _jsx } from "react/jsx-runtime";
|
|
2
|
+
import { ChartFailed } from '../charts/skeleton';
|
|
3
|
+
/**
|
|
4
|
+
* The default is empty space of the right height, not a spinner.
|
|
5
|
+
*
|
|
6
|
+
* It reserves exactly what the chart will occupy, so nothing on the host's page
|
|
7
|
+
* moves when the data lands, and it imposes no vocabulary of its own. A host
|
|
8
|
+
* that wants the package's own placeholder passes it: `loading={<ChartSkeleton
|
|
9
|
+
* kind="bar" />}`. This component cannot pick the kind for them — which chart
|
|
10
|
+
* is coming is in the payload that has not arrived yet.
|
|
11
|
+
*/
|
|
12
|
+
export function renderLoading(slot, height) {
|
|
13
|
+
if (slot === undefined)
|
|
14
|
+
return _jsx("div", { style: { height }, "aria-busy": "true" });
|
|
15
|
+
return typeof slot === 'function' ? slot() : slot;
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* The default failure says what went wrong and offers NO retry.
|
|
19
|
+
*
|
|
20
|
+
* `ChartFailed` can draw a "Try again" button and deliberately is not given the
|
|
21
|
+
* handler that would: re-running is the console's affordance, and an embed that
|
|
22
|
+
* could re-run would let any page in any application re-execute the query at
|
|
23
|
+
* will, past whatever caching sits in front of it. A host that wants a retry
|
|
24
|
+
* has a better one than a button in someone else's component — it owns the
|
|
25
|
+
* query client, and can invalidate the key.
|
|
26
|
+
*/
|
|
27
|
+
export function renderFailure(slot, error, height) {
|
|
28
|
+
if (slot === undefined) {
|
|
29
|
+
return _jsx(ChartFailed, { height: height, message: messageOf(error) });
|
|
30
|
+
}
|
|
31
|
+
return typeof slot === 'function' ? slot(error) : slot;
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* React Query types its error as `Error`, but what a transport threw is
|
|
35
|
+
* whatever the host's HTTP client throws — a string, a response object, a
|
|
36
|
+
* rejection with no shape at all. Reading `.message` off that gives `undefined`
|
|
37
|
+
* and a component that reports an empty failure, which reads as a component
|
|
38
|
+
* that failed to render rather than a chart that failed to load.
|
|
39
|
+
*/
|
|
40
|
+
export function messageOf(error) {
|
|
41
|
+
if (error instanceof Error && error.message)
|
|
42
|
+
return error.message;
|
|
43
|
+
return 'This chart could not be loaded.';
|
|
44
|
+
}
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Resolving `var(--…)` by hand, because a serialised SVG carries no stylesheet.
|
|
3
|
+
*
|
|
4
|
+
* WHY THIS EXISTS
|
|
5
|
+
* ---------------
|
|
6
|
+
* A chart drawn by any of the registered renderers gets its colour from CSS —
|
|
7
|
+
* a class, or a custom property the console theme sets on `:root`. Serialising
|
|
8
|
+
* that SVG and handing it to a canvas drops every stylesheet on the floor: the
|
|
9
|
+
* markup travels, the cascade does not. The result is a black-on-transparent
|
|
10
|
+
* rectangle that looks like a rendering bug rather than a missing stylesheet.
|
|
11
|
+
*
|
|
12
|
+
* `getComputedStyle` in a real browser substitutes custom properties before it
|
|
13
|
+
* hands a value back, so most of the time reading the computed value is enough.
|
|
14
|
+
* Most of the time is not always: a value can survive substitution in the
|
|
15
|
+
* shorthand it came from, jsdom does not substitute at all (which is how the
|
|
16
|
+
* tests for this file can be written), and a caller may want to serialise an
|
|
17
|
+
* element that is not attached to a document at all. So the substitution is
|
|
18
|
+
* done here rather than assumed, against a map collected from the live tree.
|
|
19
|
+
*
|
|
20
|
+
* The theme's variables are named explicitly instead of enumerated. A computed
|
|
21
|
+
* `CSSStyleDeclaration` is not required to list custom properties — Chrome and
|
|
22
|
+
* Firefox do, Safari historically did not, and jsdom does not — so enumerating
|
|
23
|
+
* would work in development and quietly produce a black chart in someone's
|
|
24
|
+
* browser. A named list is boring, deterministic, and extendable by the caller.
|
|
25
|
+
*/
|
|
26
|
+
/**
|
|
27
|
+
* The custom properties `packages/dashboard/src/client/styles.css` sets.
|
|
28
|
+
*
|
|
29
|
+
* `--accent`, `--text` and `--muted` are the three a chart actually paints
|
|
30
|
+
* with; the rest are here because a card's own background and hairlines are
|
|
31
|
+
* drawn from them and an export that resolves the ink but not the paper is
|
|
32
|
+
* half a fix. `--chart-1` through `--chart-5` are the five shadcn/ui reads.
|
|
33
|
+
*/
|
|
34
|
+
export declare const THEME_CUSTOM_PROPERTIES: readonly string[];
|
|
35
|
+
/**
|
|
36
|
+
* Read the named custom properties as they cascade onto `element`.
|
|
37
|
+
*
|
|
38
|
+
* Starts at the element rather than at `:root` on purpose: custom properties
|
|
39
|
+
* inherit, so a card that overrode `--accent` for itself is what the chart
|
|
40
|
+
* inside it actually painted with, and that is what the PNG should show.
|
|
41
|
+
*
|
|
42
|
+
* The walk up the ancestors is not redundant with that inheritance. A browser's
|
|
43
|
+
* computed style already reports an inherited custom property on the element,
|
|
44
|
+
* but jsdom's does not — it only reports what matched that element directly —
|
|
45
|
+
* so without the walk every one of these resolves to nothing under test and the
|
|
46
|
+
* behaviour under test stops resembling the behaviour shipped. In a browser the
|
|
47
|
+
* first read wins and the loop never runs a second time.
|
|
48
|
+
*/
|
|
49
|
+
export declare function collectCustomProperties(element: Element, names?: readonly string[], read?: (element: Element) => CSSStyleDeclaration): Map<string, string>;
|
|
50
|
+
/**
|
|
51
|
+
* Substitute every `var(--name, fallback)` in a CSS value.
|
|
52
|
+
*
|
|
53
|
+
* Written as a scanner rather than a regex because the fallback is itself a
|
|
54
|
+
* full CSS value and may contain both commas and further `var()` calls —
|
|
55
|
+
* `var(--accent, var(--text, #fff))` is legal and a regex that handles it is
|
|
56
|
+
* less readable than this. An unknown variable with no fallback resolves to the
|
|
57
|
+
* empty string, which is what the cascade does, and the caller drops empty
|
|
58
|
+
* declarations rather than writing `fill:` into the markup.
|
|
59
|
+
*/
|
|
60
|
+
export declare function resolveCssVariables(value: string, variables: ReadonlyMap<string, string>, depth?: number): string;
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Resolving `var(--…)` by hand, because a serialised SVG carries no stylesheet.
|
|
3
|
+
*
|
|
4
|
+
* WHY THIS EXISTS
|
|
5
|
+
* ---------------
|
|
6
|
+
* A chart drawn by any of the registered renderers gets its colour from CSS —
|
|
7
|
+
* a class, or a custom property the console theme sets on `:root`. Serialising
|
|
8
|
+
* that SVG and handing it to a canvas drops every stylesheet on the floor: the
|
|
9
|
+
* markup travels, the cascade does not. The result is a black-on-transparent
|
|
10
|
+
* rectangle that looks like a rendering bug rather than a missing stylesheet.
|
|
11
|
+
*
|
|
12
|
+
* `getComputedStyle` in a real browser substitutes custom properties before it
|
|
13
|
+
* hands a value back, so most of the time reading the computed value is enough.
|
|
14
|
+
* Most of the time is not always: a value can survive substitution in the
|
|
15
|
+
* shorthand it came from, jsdom does not substitute at all (which is how the
|
|
16
|
+
* tests for this file can be written), and a caller may want to serialise an
|
|
17
|
+
* element that is not attached to a document at all. So the substitution is
|
|
18
|
+
* done here rather than assumed, against a map collected from the live tree.
|
|
19
|
+
*
|
|
20
|
+
* The theme's variables are named explicitly instead of enumerated. A computed
|
|
21
|
+
* `CSSStyleDeclaration` is not required to list custom properties — Chrome and
|
|
22
|
+
* Firefox do, Safari historically did not, and jsdom does not — so enumerating
|
|
23
|
+
* would work in development and quietly produce a black chart in someone's
|
|
24
|
+
* browser. A named list is boring, deterministic, and extendable by the caller.
|
|
25
|
+
*/
|
|
26
|
+
/**
|
|
27
|
+
* The custom properties `packages/dashboard/src/client/styles.css` sets.
|
|
28
|
+
*
|
|
29
|
+
* `--accent`, `--text` and `--muted` are the three a chart actually paints
|
|
30
|
+
* with; the rest are here because a card's own background and hairlines are
|
|
31
|
+
* drawn from them and an export that resolves the ink but not the paper is
|
|
32
|
+
* half a fix. `--chart-1` through `--chart-5` are the five shadcn/ui reads.
|
|
33
|
+
*/
|
|
34
|
+
export const THEME_CUSTOM_PROPERTIES = [
|
|
35
|
+
'--bg',
|
|
36
|
+
'--panel',
|
|
37
|
+
'--line',
|
|
38
|
+
'--line-soft',
|
|
39
|
+
'--text',
|
|
40
|
+
'--muted',
|
|
41
|
+
'--accent',
|
|
42
|
+
'--chart-1',
|
|
43
|
+
'--chart-2',
|
|
44
|
+
'--chart-3',
|
|
45
|
+
'--chart-4',
|
|
46
|
+
'--chart-5',
|
|
47
|
+
];
|
|
48
|
+
/** How many substitution rounds before we assume the variables reference each other. */
|
|
49
|
+
const MAX_SUBSTITUTION_DEPTH = 8;
|
|
50
|
+
/**
|
|
51
|
+
* Read the named custom properties as they cascade onto `element`.
|
|
52
|
+
*
|
|
53
|
+
* Starts at the element rather than at `:root` on purpose: custom properties
|
|
54
|
+
* inherit, so a card that overrode `--accent` for itself is what the chart
|
|
55
|
+
* inside it actually painted with, and that is what the PNG should show.
|
|
56
|
+
*
|
|
57
|
+
* The walk up the ancestors is not redundant with that inheritance. A browser's
|
|
58
|
+
* computed style already reports an inherited custom property on the element,
|
|
59
|
+
* but jsdom's does not — it only reports what matched that element directly —
|
|
60
|
+
* so without the walk every one of these resolves to nothing under test and the
|
|
61
|
+
* behaviour under test stops resembling the behaviour shipped. In a browser the
|
|
62
|
+
* first read wins and the loop never runs a second time.
|
|
63
|
+
*/
|
|
64
|
+
export function collectCustomProperties(element, names = THEME_CUSTOM_PROPERTIES, read = (target) => window.getComputedStyle(target)) {
|
|
65
|
+
const values = new Map();
|
|
66
|
+
const remaining = new Set(names);
|
|
67
|
+
let current = element;
|
|
68
|
+
while (current && remaining.size > 0) {
|
|
69
|
+
const computed = read(current);
|
|
70
|
+
for (const name of remaining) {
|
|
71
|
+
const value = computed.getPropertyValue(name).trim();
|
|
72
|
+
if (!value)
|
|
73
|
+
continue;
|
|
74
|
+
values.set(name, value);
|
|
75
|
+
remaining.delete(name);
|
|
76
|
+
}
|
|
77
|
+
current = current.parentElement;
|
|
78
|
+
}
|
|
79
|
+
return values;
|
|
80
|
+
}
|
|
81
|
+
/** Index of the first comma that is not inside a nested function, or -1. */
|
|
82
|
+
function topLevelComma(value) {
|
|
83
|
+
let depth = 0;
|
|
84
|
+
for (let index = 0; index < value.length; index++) {
|
|
85
|
+
const character = value[index];
|
|
86
|
+
if (character === '(')
|
|
87
|
+
depth++;
|
|
88
|
+
else if (character === ')')
|
|
89
|
+
depth--;
|
|
90
|
+
else if (character === ',' && depth === 0)
|
|
91
|
+
return index;
|
|
92
|
+
}
|
|
93
|
+
return -1;
|
|
94
|
+
}
|
|
95
|
+
/** The `)` closing the `var(` that opens at `openIndex`, or -1 if unbalanced. */
|
|
96
|
+
function matchingParen(value, openIndex) {
|
|
97
|
+
let depth = 0;
|
|
98
|
+
for (let index = openIndex; index < value.length; index++) {
|
|
99
|
+
if (value[index] === '(')
|
|
100
|
+
depth++;
|
|
101
|
+
else if (value[index] === ')') {
|
|
102
|
+
depth--;
|
|
103
|
+
if (depth === 0)
|
|
104
|
+
return index;
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
return -1;
|
|
108
|
+
}
|
|
109
|
+
/**
|
|
110
|
+
* Substitute every `var(--name, fallback)` in a CSS value.
|
|
111
|
+
*
|
|
112
|
+
* Written as a scanner rather than a regex because the fallback is itself a
|
|
113
|
+
* full CSS value and may contain both commas and further `var()` calls —
|
|
114
|
+
* `var(--accent, var(--text, #fff))` is legal and a regex that handles it is
|
|
115
|
+
* less readable than this. An unknown variable with no fallback resolves to the
|
|
116
|
+
* empty string, which is what the cascade does, and the caller drops empty
|
|
117
|
+
* declarations rather than writing `fill:` into the markup.
|
|
118
|
+
*/
|
|
119
|
+
export function resolveCssVariables(value, variables, depth = 0) {
|
|
120
|
+
if (depth >= MAX_SUBSTITUTION_DEPTH)
|
|
121
|
+
return value;
|
|
122
|
+
const start = value.indexOf('var(');
|
|
123
|
+
if (start === -1)
|
|
124
|
+
return value;
|
|
125
|
+
const end = matchingParen(value, start + 3);
|
|
126
|
+
if (end === -1)
|
|
127
|
+
return value;
|
|
128
|
+
const inner = value.slice(start + 4, end);
|
|
129
|
+
const comma = topLevelComma(inner);
|
|
130
|
+
const name = (comma === -1 ? inner : inner.slice(0, comma)).trim();
|
|
131
|
+
const fallback = comma === -1 ? '' : inner.slice(comma + 1).trim();
|
|
132
|
+
const substituted = variables.get(name) ?? fallback;
|
|
133
|
+
const rewritten = value.slice(0, start) +
|
|
134
|
+
resolveCssVariables(substituted, variables, depth + 1) +
|
|
135
|
+
value.slice(end + 1);
|
|
136
|
+
return resolveCssVariables(rewritten, variables, depth + 1);
|
|
137
|
+
}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Getting a chart out of the console as a file.
|
|
3
|
+
*
|
|
4
|
+
* PNG is produced here, and deliberately: it needs no dependency at all, which
|
|
5
|
+
* is the same argument `charts/registry.tsx` makes about chart libraries. A
|
|
6
|
+
* serialised SVG, a canvas and `toBlob` are all already in the browser.
|
|
7
|
+
*
|
|
8
|
+
* PDF is NOT produced here, for the other half of that same argument — a PDF
|
|
9
|
+
* renderer is ~128KB every consumer would pay for so that some of them can
|
|
10
|
+
* export a chart, and the hosts that want one already have a document pipeline
|
|
11
|
+
* of their own. So `pdf.ts` is a seam rather than an implementation: the host
|
|
12
|
+
* registers an exporter, this package hands it the raster, the markup and the
|
|
13
|
+
* real dimensions, and where nobody registered one there is no PDF action at
|
|
14
|
+
* all — the rule `registeredChartLibraries()` already follows.
|
|
15
|
+
*/
|
|
16
|
+
export { collectCustomProperties, resolveCssVariables, THEME_CUSTOM_PROPERTIES, } from './css-variables';
|
|
17
|
+
export { type ExportBackground, resolveAncestorBackground, resolveSvgSize, type SerializedSvg, type SerializeSvgOptions, serializeSvg, svgToDataUri, } from './serialize';
|
|
18
|
+
export { defaultPngFilename, downloadSvgAsPng, findExportableSvg, type PngExportOptions, rasteriseSerializedSvg, resolveScale, svgToPngBlob, triggerDownload, } from './png';
|
|
19
|
+
export { canRasterise, type PngExport, type PngExportTarget, useHasExportableSvg, usePngExport, type UsePngExportOptions, } from './use-png-export';
|
|
20
|
+
export { buildChartPdfSource, type ChartPdfExporter, type ChartPdfSource, exportSvgAsPdf, getPdfExporter, type PdfSourceOptions, registerPdfExporter, subscribeToPdfExporter, type SvgRasteriser, } from './pdf';
|
|
21
|
+
export { type PdfExport, usePdfExport, type UsePdfExportOptions, } from './use-pdf-export';
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Getting a chart out of the console as a file.
|
|
3
|
+
*
|
|
4
|
+
* PNG is produced here, and deliberately: it needs no dependency at all, which
|
|
5
|
+
* is the same argument `charts/registry.tsx` makes about chart libraries. A
|
|
6
|
+
* serialised SVG, a canvas and `toBlob` are all already in the browser.
|
|
7
|
+
*
|
|
8
|
+
* PDF is NOT produced here, for the other half of that same argument — a PDF
|
|
9
|
+
* renderer is ~128KB every consumer would pay for so that some of them can
|
|
10
|
+
* export a chart, and the hosts that want one already have a document pipeline
|
|
11
|
+
* of their own. So `pdf.ts` is a seam rather than an implementation: the host
|
|
12
|
+
* registers an exporter, this package hands it the raster, the markup and the
|
|
13
|
+
* real dimensions, and where nobody registered one there is no PDF action at
|
|
14
|
+
* all — the rule `registeredChartLibraries()` already follows.
|
|
15
|
+
*/
|
|
16
|
+
export { collectCustomProperties, resolveCssVariables, THEME_CUSTOM_PROPERTIES, } from './css-variables';
|
|
17
|
+
export { resolveAncestorBackground, resolveSvgSize, serializeSvg, svgToDataUri, } from './serialize';
|
|
18
|
+
export { defaultPngFilename, downloadSvgAsPng, findExportableSvg, rasteriseSerializedSvg, resolveScale, svgToPngBlob, triggerDownload, } from './png';
|
|
19
|
+
export { canRasterise, useHasExportableSvg, usePngExport, } from './use-png-export';
|
|
20
|
+
export { buildChartPdfSource, exportSvgAsPdf, getPdfExporter, registerPdfExporter, subscribeToPdfExporter, } from './pdf';
|
|
21
|
+
export { usePdfExport, } from './use-pdf-export';
|