@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
@@ -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';