@dudousxd/nestjs-catalog-react 0.15.0 → 0.17.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.
@@ -0,0 +1,80 @@
1
+ /**
2
+ * Every Shiki grammar and theme a code surface in this package can ask for.
3
+ *
4
+ * WHY A LIST EXISTS AT ALL
5
+ * ------------------------
6
+ * `@pierre/diffs` resolves a language through Shiki's `bundledLanguages`, which
7
+ * is a map of ~240 dynamic imports, and a theme through `@pierre/theming`'s
8
+ * collections, which are another ~75. A bundler cannot tree-shake a dynamic
9
+ * import behind a runtime key, so it emits a chunk for every one of them:
10
+ * measured on `packages/dashboard`'s SPA, 242 language chunks totalling 7.47 MB
11
+ * minified and 75 theme chunks totalling 1.58 MB, against four grammars and two
12
+ * themes this console will ever render. None of it is in the entry path — see
13
+ * `bundler/shiki-subset.ts` for what that does and does not buy — but a
14
+ * `dist/spa` where nine tenths of the files are grammars for languages the
15
+ * catalog cannot execute is not a thing to ship to a host.
16
+ *
17
+ * So the set is stated here, once, and `shikiSubset()` prunes the registries
18
+ * down to it at build time.
19
+ *
20
+ * WHY THIS LIST CANNOT GO QUIET
21
+ * -----------------------------
22
+ * A hand-maintained list of "languages we support" is exactly the shape that
23
+ * stops being true the day somebody adds a case, and the failure is silent: an
24
+ * unpruned grammar renders, a pruned one does not, and both look like code in a
25
+ * box. Three things make that impossible here rather than merely unlikely.
26
+ *
27
+ * 1. {@link CatalogCodeLanguage} is derived from this array, and it is the type
28
+ * of `CodeEditor`'s `language` prop and `DiffBody`'s. A `language` this
29
+ * bundle does not carry is a COMPILE error at the call site.
30
+ * 2. {@link TRANSFORM_HIGHLIGHTED_AS} `satisfies Record<TransformLanguage, …>`,
31
+ * so a language added to `TRANSFORM_LANGUAGES` in `@dudousxd/nestjs-catalog`
32
+ * is a compile error here until somebody says what it is highlighted as —
33
+ * and can only be answered with a grammar named above.
34
+ * 3. `shikiSubset()` fails the BUILD if any name below is absent from the
35
+ * registry it prunes, so a typo, a rename, or a Shiki release that drops a
36
+ * grammar stops the build rather than quietly shipping plain text.
37
+ */
38
+ export declare const CATALOG_CODE_LANGUAGES: readonly ["sql", "json", "tsx", "python"];
39
+ /** Anything a code surface in this package may be told to highlight. */
40
+ export type CatalogCodeLanguage = (typeof CATALOG_CODE_LANGUAGES)[number];
41
+ /**
42
+ * The two themes, and there are only ever two.
43
+ *
44
+ * `@pierre/diffs` picks between a `dark` and a `light` theme from its own
45
+ * `DEFAULT_THEMES`, which this package never overrides — `codeOptions` passes
46
+ * `themeType` (which SIDE to paint) and no `theme` (which PALETTE), so the pair
47
+ * is always Pierre's own. Both are loaded on every mount, because the editor
48
+ * hands both to the highlighter and lets CSS choose; that is why this is a pair
49
+ * rather than the one in force.
50
+ *
51
+ * The other eight `@pierre/theme` palettes — soft, vibrant, and the two colour
52
+ * vision variants of each side — are real themes that nothing here selects.
53
+ * They are named in `@pierre/theming`'s collection all the same, so they are
54
+ * eight more chunks unless they are pruned.
55
+ */
56
+ export declare const CATALOG_CODE_THEMES: readonly ["pierre-light", "pierre-dark"];
57
+ /** One of the two palettes a code surface in this package is painted with. */
58
+ export type CatalogCodeTheme = (typeof CATALOG_CODE_THEMES)[number];
59
+ /**
60
+ * What each language a transform can be WRITTEN in is HIGHLIGHTED as.
61
+ *
62
+ * The two vocabularies are not the same and should not be conflated. A
63
+ * transform's language is what the runtime executes — `TRANSFORM_LANGUAGES`,
64
+ * answered by the deployment's `/capabilities` — while a grammar is what the
65
+ * editor tokenises with, and TSX is deliberately the answer for both JavaScript
66
+ * and TypeScript: it is a superset of each, so it colours a plain `.js` body
67
+ * correctly while also surviving the type annotations in the TypeScript starter.
68
+ * Shipping `javascript` and `typescript` beside it would be another 366 KB of
69
+ * `@shikijs/langs` (181 + 186) for output no reader could tell apart.
70
+ *
71
+ * The `satisfies` is the load-bearing part. It is what turns "somebody added a
72
+ * fourth transform language" from a pane that silently loses its colours into
73
+ * two compile errors: a missing key here, and — if the answer names a grammar
74
+ * the bundle does not carry — a value that is not a {@link CatalogCodeLanguage}.
75
+ */
76
+ export declare const TRANSFORM_HIGHLIGHTED_AS: {
77
+ javascript: "tsx";
78
+ typescript: "tsx";
79
+ python: "python";
80
+ };
@@ -0,0 +1,76 @@
1
+ /**
2
+ * Every Shiki grammar and theme a code surface in this package can ask for.
3
+ *
4
+ * WHY A LIST EXISTS AT ALL
5
+ * ------------------------
6
+ * `@pierre/diffs` resolves a language through Shiki's `bundledLanguages`, which
7
+ * is a map of ~240 dynamic imports, and a theme through `@pierre/theming`'s
8
+ * collections, which are another ~75. A bundler cannot tree-shake a dynamic
9
+ * import behind a runtime key, so it emits a chunk for every one of them:
10
+ * measured on `packages/dashboard`'s SPA, 242 language chunks totalling 7.47 MB
11
+ * minified and 75 theme chunks totalling 1.58 MB, against four grammars and two
12
+ * themes this console will ever render. None of it is in the entry path — see
13
+ * `bundler/shiki-subset.ts` for what that does and does not buy — but a
14
+ * `dist/spa` where nine tenths of the files are grammars for languages the
15
+ * catalog cannot execute is not a thing to ship to a host.
16
+ *
17
+ * So the set is stated here, once, and `shikiSubset()` prunes the registries
18
+ * down to it at build time.
19
+ *
20
+ * WHY THIS LIST CANNOT GO QUIET
21
+ * -----------------------------
22
+ * A hand-maintained list of "languages we support" is exactly the shape that
23
+ * stops being true the day somebody adds a case, and the failure is silent: an
24
+ * unpruned grammar renders, a pruned one does not, and both look like code in a
25
+ * box. Three things make that impossible here rather than merely unlikely.
26
+ *
27
+ * 1. {@link CatalogCodeLanguage} is derived from this array, and it is the type
28
+ * of `CodeEditor`'s `language` prop and `DiffBody`'s. A `language` this
29
+ * bundle does not carry is a COMPILE error at the call site.
30
+ * 2. {@link TRANSFORM_HIGHLIGHTED_AS} `satisfies Record<TransformLanguage, …>`,
31
+ * so a language added to `TRANSFORM_LANGUAGES` in `@dudousxd/nestjs-catalog`
32
+ * is a compile error here until somebody says what it is highlighted as —
33
+ * and can only be answered with a grammar named above.
34
+ * 3. `shikiSubset()` fails the BUILD if any name below is absent from the
35
+ * registry it prunes, so a typo, a rename, or a Shiki release that drops a
36
+ * grammar stops the build rather than quietly shipping plain text.
37
+ */
38
+ export const CATALOG_CODE_LANGUAGES = ['sql', 'json', 'tsx', 'python'];
39
+ /**
40
+ * The two themes, and there are only ever two.
41
+ *
42
+ * `@pierre/diffs` picks between a `dark` and a `light` theme from its own
43
+ * `DEFAULT_THEMES`, which this package never overrides — `codeOptions` passes
44
+ * `themeType` (which SIDE to paint) and no `theme` (which PALETTE), so the pair
45
+ * is always Pierre's own. Both are loaded on every mount, because the editor
46
+ * hands both to the highlighter and lets CSS choose; that is why this is a pair
47
+ * rather than the one in force.
48
+ *
49
+ * The other eight `@pierre/theme` palettes — soft, vibrant, and the two colour
50
+ * vision variants of each side — are real themes that nothing here selects.
51
+ * They are named in `@pierre/theming`'s collection all the same, so they are
52
+ * eight more chunks unless they are pruned.
53
+ */
54
+ export const CATALOG_CODE_THEMES = ['pierre-light', 'pierre-dark'];
55
+ /**
56
+ * What each language a transform can be WRITTEN in is HIGHLIGHTED as.
57
+ *
58
+ * The two vocabularies are not the same and should not be conflated. A
59
+ * transform's language is what the runtime executes — `TRANSFORM_LANGUAGES`,
60
+ * answered by the deployment's `/capabilities` — while a grammar is what the
61
+ * editor tokenises with, and TSX is deliberately the answer for both JavaScript
62
+ * and TypeScript: it is a superset of each, so it colours a plain `.js` body
63
+ * correctly while also surviving the type annotations in the TypeScript starter.
64
+ * Shipping `javascript` and `typescript` beside it would be another 366 KB of
65
+ * `@shikijs/langs` (181 + 186) for output no reader could tell apart.
66
+ *
67
+ * The `satisfies` is the load-bearing part. It is what turns "somebody added a
68
+ * fourth transform language" from a pane that silently loses its colours into
69
+ * two compile errors: a missing key here, and — if the answer names a grammar
70
+ * the bundle does not carry — a value that is not a {@link CatalogCodeLanguage}.
71
+ */
72
+ export const TRANSFORM_HIGHLIGHTED_AS = {
73
+ javascript: 'tsx',
74
+ typescript: 'tsx',
75
+ python: 'python',
76
+ };
@@ -0,0 +1,25 @@
1
+ /**
2
+ * Which way round every code surface in this package should be painted.
3
+ *
4
+ * WHY THIS IS NOT JUST `themeType: 'system'`
5
+ * -----------------------------------------
6
+ * `@pierre/diffs` paints itself from a Shiki theme and takes a `themeType` of
7
+ * `'system' | 'light' | 'dark'`, where `'system'` means `prefers-color-scheme`.
8
+ * Everything else in this package is painted by Tailwind's `dark:` variant, and
9
+ * Tailwind supports TWO strategies for that: `media` (which is
10
+ * `prefers-color-scheme`, and matches `'system'`) and `class` (which is a `dark`
11
+ * class the host toggles, and does not).
12
+ *
13
+ * This package ships no Tailwind config — the host owns it — so it cannot know
14
+ * which one is in play, and guessing wrong is the failure the old Prism theme
15
+ * had: a code box painted for one surface sitting on the other, which reads as
16
+ * dark-on-dark rather than as a bug. So both are honoured. A `dark` class on
17
+ * `<html>` or `<body>` is a deliberate statement and wins; with no class the
18
+ * question falls back to the media query, which is what `'system'` already does.
19
+ *
20
+ * The class is watched rather than read once, because a theme toggle is a
21
+ * runtime event and a code editor that keeps yesterday's palette until a reload
22
+ * is the same complaint in a slower form.
23
+ */
24
+ export type CodeThemeType = 'system' | 'light' | 'dark';
25
+ export declare function useCodeThemeType(): CodeThemeType;
@@ -0,0 +1,26 @@
1
+ import { useEffect, useState } from 'react';
2
+ /** The class Tailwind's `class` strategy toggles, and every host that uses it toggles. */
3
+ const DARK_CLASS = 'dark';
4
+ function readThemeType() {
5
+ if (typeof document === 'undefined')
6
+ return 'system';
7
+ const marked = document.documentElement.classList.contains(DARK_CLASS) ||
8
+ document.body?.classList.contains(DARK_CLASS);
9
+ return marked ? 'dark' : 'system';
10
+ }
11
+ export function useCodeThemeType() {
12
+ const [themeType, setThemeType] = useState(readThemeType);
13
+ useEffect(() => {
14
+ const sync = () => setThemeType(readThemeType());
15
+ sync();
16
+ const observer = new MutationObserver(sync);
17
+ // `class` only. Observing everything would re-run this on every attribute
18
+ // React writes to `<body>`, and the answer can only change with the class.
19
+ observer.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] });
20
+ if (document.body) {
21
+ observer.observe(document.body, { attributes: true, attributeFilter: ['class'] });
22
+ }
23
+ return () => observer.disconnect();
24
+ }, []);
25
+ return themeType;
26
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dudousxd/nestjs-catalog-react",
3
- "version": "0.15.0",
3
+ "version": "0.17.0",
4
4
  "description": "Ready-made React screens for @dudousxd/nestjs-catalog — a model manager and a generic object explorer you can drop into your own app shell.",
5
5
  "license": "MIT",
6
6
  "author": "Davide Carvalho",
@@ -35,6 +35,10 @@
35
35
  "./workflow": {
36
36
  "types": "./dist/workflow/index.d.ts",
37
37
  "default": "./dist/workflow/index.js"
38
+ },
39
+ "./bundler": {
40
+ "types": "./dist/bundler/index.d.ts",
41
+ "default": "./dist/bundler/index.js"
38
42
  }
39
43
  },
40
44
  "files": [
@@ -43,10 +47,17 @@
43
47
  ],
44
48
  "peerDependencies": {
45
49
  "@base-ui/react": ">=1.6.0",
50
+ "@pierre/diffs": ">=1.3.3",
46
51
  "@dnd-kit/core": ">=6",
47
52
  "@dnd-kit/sortable": ">=10",
48
53
  "@dnd-kit/utilities": ">=3",
54
+ "@dudousxd/nestjs-catalog": ">=0.1.0",
49
55
  "@tanstack/react-query": ">=5",
56
+ "@tanstack/react-table": ">=9",
57
+ "@tiptap/core": ">=3",
58
+ "@tiptap/pm": ">=3",
59
+ "@tiptap/react": ">=3",
60
+ "@tiptap/starter-kit": ">=3",
50
61
  "@visx/curve": "4.0.1-alpha.0",
51
62
  "@visx/event": "4.0.1-alpha.0",
52
63
  "@visx/grid": "4.0.1-alpha.0",
@@ -59,24 +70,23 @@
59
70
  "d3-shape": ">=3",
60
71
  "lucide-react": ">=0.400.0",
61
72
  "motion": ">=11",
62
- "prism-react-renderer": ">=2.4.0",
63
73
  "react": ">=18",
64
74
  "react-dom": ">=18",
65
75
  "recharts": ">=2.12.0",
66
- "@dudousxd/nestjs-catalog": ">=0.1.0",
67
- "@tanstack/react-table": ">=9",
68
- "@tiptap/react": ">=3",
69
- "@tiptap/starter-kit": ">=3",
70
- "@tiptap/pm": ">=3",
71
- "tiptap-markdown": ">=0.9",
72
- "@tiptap/core": ">=3"
76
+ "tiptap-markdown": ">=0.9"
73
77
  },
74
78
  "devDependencies": {
75
79
  "@base-ui/react": "1.6.0",
76
80
  "@dnd-kit/core": "6.3.1",
77
81
  "@dnd-kit/sortable": "10.0.0",
78
82
  "@dnd-kit/utilities": "3.2.2",
83
+ "@pierre/diffs": "1.3.3",
79
84
  "@tanstack/react-query": "5.99.2",
85
+ "@tanstack/react-table": "9.0.0",
86
+ "@tiptap/core": "3.29.2",
87
+ "@tiptap/pm": "3.29.2",
88
+ "@tiptap/react": "3.29.2",
89
+ "@tiptap/starter-kit": "3.29.2",
80
90
  "@types/d3-array": "^3.2.2",
81
91
  "@types/d3-shape": "^3.1.8",
82
92
  "@types/react": "19.2.14",
@@ -94,19 +104,13 @@
94
104
  "d3-shape": "^3.2.0",
95
105
  "lucide-react": "0.552.0",
96
106
  "motion": "^12.43.0",
97
- "prism-react-renderer": "2.4.1",
98
107
  "react": "19.2.0",
99
108
  "react-dom": "19.2.0",
100
109
  "recharts": "2.15.4",
101
110
  "tailwind-merge": "3.4.1",
102
- "typescript": "5.9.3",
103
- "@tanstack/react-table": "9.0.0",
104
- "@tiptap/react": "3.29.2",
105
- "@tiptap/starter-kit": "3.29.2",
106
- "@tiptap/pm": "3.29.2",
107
111
  "tiptap-markdown": "0.9.0",
108
- "@tiptap/core": "3.29.2",
109
- "@dudousxd/nestjs-catalog": "0.12.0"
112
+ "typescript": "5.9.3",
113
+ "@dudousxd/nestjs-catalog": "0.14.0"
110
114
  },
111
115
  "dependencies": {
112
116
  "clsx": "2.1.1",
@@ -1,124 +0,0 @@
1
- /**
2
- * Two texts, lined up, computed in this file and nowhere else.
3
- *
4
- * WHY THIS IS HAND-ROLLED
5
- * -----------------------
6
- * The two strings this console ever diffs are a transform's code and a saved
7
- * query's SQL. Those are the most sensitive strings in the product: a transform
8
- * is executable code with the catalog's own database reachable from it, and a
9
- * saved query is somebody's SQL against military logistics data — the column
10
- * names alone describe a fleet. A diff library is a dependency that gets to see
11
- * both, on every render, and "it only renders locally" is a property of the
12
- * version you audited rather than of the package. There is no version of this
13
- * feature worth a supply-chain question mark on that content, so there is no
14
- * dependency here at all: `diffLines` is forty lines of dynamic programming with
15
- * no imports, and the whole of what it can do is visible on this screen.
16
- *
17
- * It is also the cheaper answer. This package already declines dependencies it
18
- * could plausibly justify — `charts/css.tsx` draws bars with divs, `ui/button.tsx`
19
- * hand-rolls what `class-variance-authority` would compile to, and `export/pdf.ts`
20
- * is a seam rather than a renderer — for the same reason each time: every
21
- * consumer pays for it whether or not they render this screen.
22
- *
23
- * WHAT IT DOES NOT DO
24
- * -------------------
25
- * No word- or character-level diff inside a changed line, and no move detection.
26
- * A changed line is reported as a removal and an addition, which is what a
27
- * unified diff has always done and what the renderer colours. Both are real
28
- * improvements somebody could make; neither is the question this screen exists
29
- * to answer, which is "which lines are different between the version that ran
30
- * and the version that is current".
31
- */
32
- /**
33
- * The largest DP table this will build, in cells.
34
- *
35
- * The comparison is O(n·m) in the CHANGED region only — the common prefix and
36
- * suffix are trimmed first, so the ordinary case (somebody edited four lines of
37
- * a three-hundred-line transform) is a handful of cells regardless of file size.
38
- * This bound exists for the case that survives the trim: two bodies that share
39
- * almost nothing, which is what a rewrite looks like.
40
- *
41
- * 1.5M cells is a `Uint32Array` of 6MB and roughly a 1,200×1,200 changed region.
42
- * Past that the table costs more memory than the browser tab should spend on a
43
- * comparison nobody could read anyway, so {@link diffLines} stops computing and
44
- * SAYS it stopped — see `alignment`. A silent fallback would be the same failure
45
- * `capLines` names one package over: a truncation nobody is told about.
46
- */
47
- export declare const DIFF_MAX_CELLS = 1500000;
48
- /** What happened to one line between the two bodies. */
49
- export type DiffOp = 'same' | 'added' | 'removed';
50
- export interface DiffLine {
51
- op: DiffOp;
52
- /** 1-based line number in the earlier body. Null on an added line. */
53
- before: number | null;
54
- /** 1-based line number in the later body. Null on a removed line. */
55
- after: number | null;
56
- text: string;
57
- }
58
- export interface LineDiff {
59
- lines: DiffLine[];
60
- added: number;
61
- removed: number;
62
- /**
63
- * The two bodies are byte-for-byte the same.
64
- *
65
- * A separate field rather than `added === 0 && removed === 0`, because the
66
- * caller has to distinguish "these two versions are identical" from "there is
67
- * no second version to compare against", and only one of those is a statement
68
- * about the texts. See `RevisionDiff`, where conflating them is the exact
69
- * thing the empty states are written to avoid.
70
- */
71
- identical: boolean;
72
- /**
73
- * How the lines were matched up.
74
- *
75
- * `exact` means every line was lined up against its counterpart. `coarse`
76
- * means the changed region was past {@link DIFF_MAX_CELLS} and the whole of it
77
- * is reported as removed-then-added — true, but blunter than it could be, and
78
- * the screen says so rather than letting somebody read "everything changed" as
79
- * a finding about their code.
80
- */
81
- alignment: 'exact' | 'coarse';
82
- }
83
- /**
84
- * Line up two bodies.
85
- *
86
- * `before` is the earlier version, `after` the later one. The order matters to
87
- * the reading and not to the algorithm: swapping them turns every addition into
88
- * a removal, which is why the caller that pins "the version that ran" on the
89
- * left is the one that gets a screen answering "what changed since".
90
- */
91
- export declare function diffLines(before: string, after: string): LineDiff;
92
- /** Lines to keep either side of a change before folding the rest away. */
93
- export declare const DIFF_CONTEXT_LINES = 3;
94
- /**
95
- * The smallest run worth putting a button on.
96
- *
97
- * Folding two lines behind a control that says "2 unchanged lines" costs a row
98
- * to save two, and it costs a click. Below this the run is simply shown.
99
- */
100
- export declare const DIFF_MIN_FOLD = 4;
101
- export type DiffSection = {
102
- kind: 'shown';
103
- lines: DiffLine[];
104
- } | {
105
- kind: 'folded';
106
- lines: DiffLine[];
107
- };
108
- /**
109
- * Collapse the long unchanged stretches, keeping context around every change.
110
- *
111
- * A transform can be hundreds of lines and the answer to "why did Tuesday's load
112
- * differ from Monday's" is almost never more than a handful of them. Rendering
113
- * all of it puts the four lines that matter somewhere in the middle of a wall
114
- * and makes the reader scroll for them.
115
- *
116
- * Folded rather than dropped, and the sections carry their lines rather than a
117
- * count, so the renderer can expand one in place. A diff that hides code with no
118
- * way to see it is a diff you cannot trust, and this is code somebody is about
119
- * to make a decision about.
120
- *
121
- * A run at the very start or end of the file gets no context on that side —
122
- * there is no change up there to be in the context of.
123
- */
124
- export declare function foldUnchanged(lines: DiffLine[], context?: number, minFold?: number): DiffSection[];