@dudousxd/nestjs-catalog-react 0.8.0 → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +41 -5
- package/dist/DashboardBoard.d.ts +22 -0
- package/dist/DashboardBoard.js +88 -67
- 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/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,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';
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
import { type PngExportOptions } from './png';
|
|
2
|
+
import { type SerializedSvg } from './serialize';
|
|
3
|
+
/**
|
|
4
|
+
* PDF export, as a seam the host fills rather than a dependency this package takes.
|
|
5
|
+
*
|
|
6
|
+
* WHY THERE IS NO PDF RENDERER IN HERE
|
|
7
|
+
* ------------------------------------
|
|
8
|
+
* The same argument `charts/registry.tsx` makes about recharts and bklit, with
|
|
9
|
+
* the numbers on the other side of it. A client-side PDF means `jspdf` (109KB
|
|
10
|
+
* gzipped) plus `svg2pdf.js` (19KB) — ~128KB that every consumer of this
|
|
11
|
+
* library downloads so that some of them can export a chart. Meanwhile the
|
|
12
|
+
* applications that actually want this already generate PDFs server-side, with
|
|
13
|
+
* their own fonts, header, page furniture and pipeline; a PDF produced here
|
|
14
|
+
* would match none of it and would have to be styled back out again.
|
|
15
|
+
*
|
|
16
|
+
* So the host registers something that turns an exported chart into a PDF:
|
|
17
|
+
*
|
|
18
|
+
* ```ts
|
|
19
|
+
* import { registerPdfExporter } from "@dudousxd/nestjs-catalog-react";
|
|
20
|
+
*
|
|
21
|
+
* registerPdfExporter({
|
|
22
|
+
* label: "Save as report",
|
|
23
|
+
* async export({ png, width, height, title }) {
|
|
24
|
+
* const body = new FormData();
|
|
25
|
+
* body.append("chart", png, "chart.png");
|
|
26
|
+
* body.append("meta", JSON.stringify({ width, height, title }));
|
|
27
|
+
* await fetch("/reports/chart", { method: "POST", body });
|
|
28
|
+
* },
|
|
29
|
+
* });
|
|
30
|
+
* ```
|
|
31
|
+
*
|
|
32
|
+
* WHY BOTH THE RASTER AND THE MARKUP
|
|
33
|
+
* ----------------------------------
|
|
34
|
+
* A host on `@react-pdf/renderer` takes `png`, because that library draws
|
|
35
|
+
* images and not arbitrary SVG. A host with a vector pipeline takes `svg` and
|
|
36
|
+
* gets text that is still selectable and still sharp at print size. Handing
|
|
37
|
+
* over only the raster forecloses the second; handing over only the markup
|
|
38
|
+
* makes the common case do work it should not have to. Both are produced from
|
|
39
|
+
* ONE serialisation, so the two always describe the same chart at the same
|
|
40
|
+
* size — see {@link rasteriseSerializedSvg}.
|
|
41
|
+
*
|
|
42
|
+
* WHERE NOBODY REGISTERED ONE, THERE IS NO ACTION
|
|
43
|
+
* -----------------------------------------------
|
|
44
|
+
* Not a disabled button, not one that fails when clicked: absent. That is the
|
|
45
|
+
* rule `registeredChartLibraries()` already follows, and it is the rule
|
|
46
|
+
* `usePdfExport` implements — a control that claims something the code does not
|
|
47
|
+
* do is a bug report filed against whoever shipped the control.
|
|
48
|
+
*/
|
|
49
|
+
/**
|
|
50
|
+
* What the host is handed. One chart, in the two forms this package can produce.
|
|
51
|
+
*/
|
|
52
|
+
export interface ChartPdfSource {
|
|
53
|
+
/** The rasterised chart. What an image-drawing PDF library wants. */
|
|
54
|
+
png: Blob;
|
|
55
|
+
/** The same chart as a standalone, self-contained SVG document, styles inlined. */
|
|
56
|
+
svg: string;
|
|
57
|
+
/** CSS pixels, so the host can size a page honestly. Describes both `png` and `svg`. */
|
|
58
|
+
width: number;
|
|
59
|
+
height: number;
|
|
60
|
+
/** The card's title, when it has one. */
|
|
61
|
+
title?: string;
|
|
62
|
+
/** The SQL behind the chart, for a host that prints it as a caption. */
|
|
63
|
+
query?: string;
|
|
64
|
+
}
|
|
65
|
+
export interface ChartPdfExporter {
|
|
66
|
+
/**
|
|
67
|
+
* Shown on the action, so the host names its own document.
|
|
68
|
+
*
|
|
69
|
+
* Absent means the caller draws whatever it calls this by default. It is here
|
|
70
|
+
* because the host is the one producing the artefact: "Save as PDF" is wrong
|
|
71
|
+
* for something that lands in a quarterly report template, and the component
|
|
72
|
+
* offering the button cannot know which it is.
|
|
73
|
+
*/
|
|
74
|
+
label?: string;
|
|
75
|
+
export(chart: ChartPdfSource): Promise<void>;
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* Register the host's exporter. Returns a function that removes it again.
|
|
79
|
+
*
|
|
80
|
+
* The disposer is deliberately not a plain `exporter = undefined`: it clears the
|
|
81
|
+
* slot only if this exporter is still the one in it. A host that swaps
|
|
82
|
+
* implementations — or a test that registers a second — would otherwise have
|
|
83
|
+
* the older disposer wipe the newer registration, and the symptom is the action
|
|
84
|
+
* silently disappearing long after the call that caused it.
|
|
85
|
+
*/
|
|
86
|
+
export declare function registerPdfExporter(next: ChartPdfExporter): () => void;
|
|
87
|
+
/** The registered exporter, or undefined when the host wired none. */
|
|
88
|
+
export declare function getPdfExporter(): ChartPdfExporter | undefined;
|
|
89
|
+
/**
|
|
90
|
+
* Subscribe to registration changes.
|
|
91
|
+
*
|
|
92
|
+
* `getChartRenderer` has no equivalent and does not need one: it is read while
|
|
93
|
+
* rendering a card that re-renders whenever its query result does. This is read
|
|
94
|
+
* to decide whether a control EXISTS, and the whole premise above is that a
|
|
95
|
+
* host's PDF pipeline is heavy — so it is very often behind a dynamic import
|
|
96
|
+
* that resolves after the console has already mounted. Without this, those
|
|
97
|
+
* cards would sit there actionless until something unrelated re-rendered them.
|
|
98
|
+
*/
|
|
99
|
+
export declare function subscribeToPdfExporter(listener: () => void): () => void;
|
|
100
|
+
export interface PdfSourceOptions extends PngExportOptions {
|
|
101
|
+
/** The card's title, passed through to the exporter. */
|
|
102
|
+
title?: string;
|
|
103
|
+
/** The query behind the chart, passed through to the exporter. */
|
|
104
|
+
query?: string;
|
|
105
|
+
}
|
|
106
|
+
/**
|
|
107
|
+
* How the raster is produced. A parameter so a test can substitute it.
|
|
108
|
+
*
|
|
109
|
+
* jsdom cannot rasterise — `canvas.getContext('2d')` returns null — so a test
|
|
110
|
+
* that wants to check what reaches the exporter has no other way in. The
|
|
111
|
+
* substitution stops at the raster: `serializeSvg` still runs for real, so the
|
|
112
|
+
* markup and the dimensions a test observes are the ones a browser would see.
|
|
113
|
+
*/
|
|
114
|
+
export type SvgRasteriser = (serialized: SerializedSvg, options: PngExportOptions) => Promise<Blob>;
|
|
115
|
+
/**
|
|
116
|
+
* Everything the host needs, from one serialisation of one chart.
|
|
117
|
+
*
|
|
118
|
+
* Separate from {@link exportSvgAsPdf} because it is the whole contract of the
|
|
119
|
+
* seam and nothing about it is React: a host with its own toolbar can build the
|
|
120
|
+
* payload and route it wherever it likes.
|
|
121
|
+
*/
|
|
122
|
+
export declare function buildChartPdfSource(svg: SVGSVGElement, options?: PdfSourceOptions, rasterise?: SvgRasteriser): Promise<ChartPdfSource>;
|
|
123
|
+
/**
|
|
124
|
+
* Build the payload and hand it to the registered exporter.
|
|
125
|
+
*
|
|
126
|
+
* Throws when nobody registered one. That is not the path a user can reach —
|
|
127
|
+
* `usePdfExport` reports no action at all in that case — so reaching it means a
|
|
128
|
+
* caller offered the export without checking, and a thrown error naming the
|
|
129
|
+
* missing registration is far more use than a silent no-op that looks like the
|
|
130
|
+
* PDF pipeline failing.
|
|
131
|
+
*
|
|
132
|
+
* A rejection from the host's own exporter propagates untouched. Swallowing it
|
|
133
|
+
* would leave a user who clicked "export" watching nothing happen, with the
|
|
134
|
+
* only evidence in a console they are not looking at.
|
|
135
|
+
*/
|
|
136
|
+
export declare function exportSvgAsPdf(svg: SVGSVGElement, options?: PdfSourceOptions, rasterise?: SvgRasteriser): Promise<ChartPdfSource>;
|