@thedatagrid/docs-kit 0.0.0-stage → 0.1.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/CHANGELOG.md +7 -0
- package/README.md +123 -2
- package/dist/code/demoFiles.d.ts +14 -0
- package/dist/code/demoFiles.d.ts.map +1 -0
- package/dist/code/demoFiles.js +46 -0
- package/dist/code/demoFiles.js.map +1 -0
- package/dist/code/heights.d.ts +17 -0
- package/dist/code/heights.d.ts.map +1 -0
- package/dist/code/heights.js +40 -0
- package/dist/code/heights.js.map +1 -0
- package/dist/code/highlightSpec.d.ts +34 -0
- package/dist/code/highlightSpec.d.ts.map +1 -0
- package/dist/code/highlightSpec.js +119 -0
- package/dist/code/highlightSpec.js.map +1 -0
- package/dist/code/imports.d.ts +5 -0
- package/dist/code/imports.d.ts.map +1 -0
- package/dist/code/imports.js +17 -0
- package/dist/code/imports.js.map +1 -0
- package/dist/code/index.d.ts +8 -0
- package/dist/code/index.d.ts.map +1 -0
- package/dist/code/index.js +8 -0
- package/dist/code/index.js.map +1 -0
- package/dist/code/lineRanges.d.ts +5 -0
- package/dist/code/lineRanges.d.ts.map +1 -0
- package/dist/code/lineRanges.js +35 -0
- package/dist/code/lineRanges.js.map +1 -0
- package/dist/code/regions.d.ts +53 -0
- package/dist/code/regions.d.ts.map +1 -0
- package/dist/code/regions.js +237 -0
- package/dist/code/regions.js.map +1 -0
- package/dist/code/shiki.d.ts +58 -0
- package/dist/code/shiki.d.ts.map +1 -0
- package/dist/code/shiki.js +244 -0
- package/dist/code/shiki.js.map +1 -0
- package/dist/demos/build.d.ts +17 -0
- package/dist/demos/build.d.ts.map +1 -0
- package/dist/demos/build.js +426 -0
- package/dist/demos/build.js.map +1 -0
- package/dist/demos/cli.d.ts +3 -0
- package/dist/demos/cli.d.ts.map +1 -0
- package/dist/demos/cli.js +68 -0
- package/dist/demos/cli.js.map +1 -0
- package/dist/demos/client.d.ts +27 -0
- package/dist/demos/client.d.ts.map +1 -0
- package/dist/demos/client.js +61 -0
- package/dist/demos/client.js.map +1 -0
- package/dist/demos/compile/core.d.ts +64 -0
- package/dist/demos/compile/core.d.ts.map +1 -0
- package/dist/demos/compile/core.js +174 -0
- package/dist/demos/compile/core.js.map +1 -0
- package/dist/demos/config.d.ts +108 -0
- package/dist/demos/config.d.ts.map +1 -0
- package/dist/demos/config.js +4 -0
- package/dist/demos/config.js.map +1 -0
- package/dist/demos/devEvents.d.ts +13 -0
- package/dist/demos/devEvents.d.ts.map +1 -0
- package/dist/demos/devEvents.js +45 -0
- package/dist/demos/devEvents.js.map +1 -0
- package/dist/demos/html.d.ts +21 -0
- package/dist/demos/html.d.ts.map +1 -0
- package/dist/demos/html.js +57 -0
- package/dist/demos/html.js.map +1 -0
- package/dist/demos/index.d.ts +8 -0
- package/dist/demos/index.d.ts.map +1 -0
- package/dist/demos/index.js +6 -0
- package/dist/demos/index.js.map +1 -0
- package/dist/demos/pages.d.ts +15 -0
- package/dist/demos/pages.d.ts.map +1 -0
- package/dist/demos/pages.js +71 -0
- package/dist/demos/pages.js.map +1 -0
- package/dist/demos/runtime/iframe.d.ts +50 -0
- package/dist/demos/runtime/iframe.d.ts.map +1 -0
- package/dist/demos/runtime/iframe.js +245 -0
- package/dist/demos/runtime/iframe.js.map +1 -0
- package/dist/demos/runtime/react.d.ts +3 -0
- package/dist/demos/runtime/react.d.ts.map +1 -0
- package/dist/demos/runtime/react.js +17 -0
- package/dist/demos/runtime/react.js.map +1 -0
- package/dist/demos/slug.d.ts +3 -0
- package/dist/demos/slug.d.ts.map +1 -0
- package/dist/demos/slug.js +11 -0
- package/dist/demos/slug.js.map +1 -0
- package/dist/demos/vendor.d.ts +32 -0
- package/dist/demos/vendor.d.ts.map +1 -0
- package/dist/demos/vendor.js +127 -0
- package/dist/demos/vendor.js.map +1 -0
- package/dist/demos/worker/compile.worker.d.ts +2 -0
- package/dist/demos/worker/compile.worker.d.ts.map +1 -0
- package/dist/demos/worker/compile.worker.js +27 -0
- package/dist/demos/worker/compile.worker.js.map +1 -0
- package/dist/fork/codesandbox.d.ts +39 -0
- package/dist/fork/codesandbox.d.ts.map +1 -0
- package/dist/fork/codesandbox.js +156 -0
- package/dist/fork/codesandbox.js.map +1 -0
- package/dist/fork/index.d.ts +2 -0
- package/dist/fork/index.d.ts.map +1 -0
- package/dist/fork/index.js +2 -0
- package/dist/fork/index.js.map +1 -0
- package/dist/react/Demo.d.ts +80 -0
- package/dist/react/Demo.d.ts.map +1 -0
- package/dist/react/Demo.js +156 -0
- package/dist/react/Demo.js.map +1 -0
- package/dist/react/DemoIframe.d.ts +22 -0
- package/dist/react/DemoIframe.d.ts.map +1 -0
- package/dist/react/DemoIframe.js +123 -0
- package/dist/react/DemoIframe.js.map +1 -0
- package/dist/react/DemoShell.d.ts +47 -0
- package/dist/react/DemoShell.d.ts.map +1 -0
- package/dist/react/DemoShell.js +341 -0
- package/dist/react/DemoShell.js.map +1 -0
- package/dist/react/devEvents.d.ts +17 -0
- package/dist/react/devEvents.d.ts.map +1 -0
- package/dist/react/devEvents.js +30 -0
- package/dist/react/devEvents.js.map +1 -0
- package/dist/react/editor.d.ts +8 -0
- package/dist/react/editor.d.ts.map +1 -0
- package/dist/react/editor.js +52 -0
- package/dist/react/editor.js.map +1 -0
- package/dist/react/fork.d.ts +10 -0
- package/dist/react/fork.d.ts.map +1 -0
- package/dist/react/fork.js +30 -0
- package/dist/react/fork.js.map +1 -0
- package/dist/react/index.d.ts +4 -0
- package/dist/react/index.d.ts.map +1 -0
- package/dist/react/index.js +4 -0
- package/dist/react/index.js.map +1 -0
- package/dist/react/styles.css +493 -0
- package/dist/remark/index.d.ts +3 -0
- package/dist/remark/index.d.ts.map +1 -0
- package/dist/remark/index.js +3 -0
- package/dist/remark/index.js.map +1 -0
- package/dist/remark/meta.d.ts +7 -0
- package/dist/remark/meta.d.ts.map +1 -0
- package/dist/remark/meta.js +20 -0
- package/dist/remark/meta.js.map +1 -0
- package/dist/remark/remarkDemoFences.d.ts +77 -0
- package/dist/remark/remarkDemoFences.d.ts.map +1 -0
- package/dist/remark/remarkDemoFences.js +259 -0
- package/dist/remark/remarkDemoFences.js.map +1 -0
- package/package.json +106 -4
- package/src/code/demoFiles.ts +54 -0
- package/src/code/heights.ts +47 -0
- package/src/code/highlightSpec.ts +139 -0
- package/src/code/imports.ts +18 -0
- package/src/code/index.ts +46 -0
- package/src/code/lineRanges.ts +31 -0
- package/src/code/regions.ts +270 -0
- package/src/code/shiki.ts +271 -0
- package/src/demos/build.ts +477 -0
- package/src/demos/cli.ts +64 -0
- package/src/demos/client.ts +82 -0
- package/src/demos/compile/core.ts +228 -0
- package/src/demos/config.ts +106 -0
- package/src/demos/devEvents.ts +45 -0
- package/src/demos/html.ts +74 -0
- package/src/demos/index.ts +25 -0
- package/src/demos/pages.ts +79 -0
- package/src/demos/runtime/iframe.ts +262 -0
- package/src/demos/runtime/react.ts +19 -0
- package/src/demos/slug.ts +10 -0
- package/src/demos/vendor.ts +142 -0
- package/src/demos/worker/compile.worker.ts +35 -0
- package/src/fork/codesandbox.ts +189 -0
- package/src/fork/index.ts +10 -0
- package/src/react/Demo.tsx +250 -0
- package/src/react/DemoIframe.tsx +165 -0
- package/src/react/DemoShell.tsx +592 -0
- package/src/react/devEvents.ts +34 -0
- package/src/react/editor.ts +61 -0
- package/src/react/fork.ts +31 -0
- package/src/react/index.ts +10 -0
- package/src/react/styles.css +493 -0
- package/src/remark/index.ts +2 -0
- package/src/remark/meta.ts +20 -0
- package/src/remark/remarkDemoFences.ts +330 -0
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Highlighted lines plus optional labels, keyed by the first displayed line
|
|
3
|
+
* of each labelled block. Produced from `#highlight` markers in the source
|
|
4
|
+
* (see `extractCodeMarkers`) and serialized into fence meta as
|
|
5
|
+
* `{1-3,8="label"}` so markdown-level shiki transformers can read it.
|
|
6
|
+
*/
|
|
7
|
+
export type HighlightSpec = {
|
|
8
|
+
lines: number[];
|
|
9
|
+
labels: Record<number, string>;
|
|
10
|
+
};
|
|
11
|
+
|
|
12
|
+
export type HighlightAnnotation = {
|
|
13
|
+
lines: number[];
|
|
14
|
+
label?: string;
|
|
15
|
+
};
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* `{1-3,7}` or `{8="label", 9-10="hello"}` in a fence meta string.
|
|
19
|
+
* Quoted labels may contain commas; braces inside quotes are not supported.
|
|
20
|
+
*/
|
|
21
|
+
export const HIGHLIGHT_META_RE = /\{((?:[^"{}]|"(?:\\.|[^"\\])*")*)\}/;
|
|
22
|
+
|
|
23
|
+
/** `lines` in a fence meta string: show a gutter with line numbers. */
|
|
24
|
+
export const LINES_META_RE = /(?:^|\s)lines(?:\s|$)/;
|
|
25
|
+
|
|
26
|
+
/** `originalLines="12-14"`, written for `region` fences so the gutter shows file line numbers. */
|
|
27
|
+
export const ORIGINAL_LINES_META_RE = /(?:^|\s)originalLines="([^"]+)"/;
|
|
28
|
+
|
|
29
|
+
/** `height=small` / `height="small"` in a fence meta string. */
|
|
30
|
+
export const HEIGHT_META_RE = /(?:^|\s)height="?([^\s"]+)"?/;
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* Parses the inside of a `{…}` highlight group: unlabeled ranges (`1-3,7`)
|
|
34
|
+
* and labeled ones (`8="available columns", 9-10="hello"`).
|
|
35
|
+
*/
|
|
36
|
+
export function parseHighlightMeta(inner: string): HighlightAnnotation[] {
|
|
37
|
+
const annotations: HighlightAnnotation[] = [];
|
|
38
|
+
const s = inner;
|
|
39
|
+
let i = 0;
|
|
40
|
+
|
|
41
|
+
const skipSep = () => {
|
|
42
|
+
while (i < s.length && /[\s,]/.test(s[i])) i++;
|
|
43
|
+
};
|
|
44
|
+
|
|
45
|
+
const readNumber = (): number | null => {
|
|
46
|
+
const start = i;
|
|
47
|
+
while (i < s.length && /\d/.test(s[i])) i++;
|
|
48
|
+
if (i === start) return null;
|
|
49
|
+
return Number(s.slice(start, i));
|
|
50
|
+
};
|
|
51
|
+
|
|
52
|
+
while (i < s.length) {
|
|
53
|
+
skipSep();
|
|
54
|
+
if (i >= s.length) break;
|
|
55
|
+
|
|
56
|
+
const start = readNumber();
|
|
57
|
+
if (start == null) {
|
|
58
|
+
throw new Error(`invalid highlight \`{${inner}}\` — expected a line number`);
|
|
59
|
+
}
|
|
60
|
+
let end = start;
|
|
61
|
+
if (s[i] === '-') {
|
|
62
|
+
i++;
|
|
63
|
+
const stop = readNumber();
|
|
64
|
+
if (stop == null) {
|
|
65
|
+
throw new Error(`invalid highlight \`{${inner}}\` — expected a line number after "-"`);
|
|
66
|
+
}
|
|
67
|
+
end = stop;
|
|
68
|
+
}
|
|
69
|
+
if (end < start) {
|
|
70
|
+
throw new Error(`invalid highlight \`{${inner}}\` — range ${start}-${end} goes backwards`);
|
|
71
|
+
}
|
|
72
|
+
const lines: number[] = [];
|
|
73
|
+
for (let line = start; line <= end; line++) lines.push(line);
|
|
74
|
+
|
|
75
|
+
while (i < s.length && /\s/.test(s[i])) i++;
|
|
76
|
+
let label: string | undefined;
|
|
77
|
+
if (s[i] === '=') {
|
|
78
|
+
i++;
|
|
79
|
+
while (i < s.length && /\s/.test(s[i])) i++;
|
|
80
|
+
const quote = s[i];
|
|
81
|
+
if (quote !== '"' && quote !== "'") {
|
|
82
|
+
throw new Error(`invalid highlight \`{${inner}}\` — labels must be quoted ("...")`);
|
|
83
|
+
}
|
|
84
|
+
i++;
|
|
85
|
+
let value = '';
|
|
86
|
+
while (i < s.length && s[i] !== quote) {
|
|
87
|
+
if (s[i] === '\\' && i + 1 < s.length) {
|
|
88
|
+
value += s[i + 1];
|
|
89
|
+
i += 2;
|
|
90
|
+
continue;
|
|
91
|
+
}
|
|
92
|
+
value += s[i];
|
|
93
|
+
i++;
|
|
94
|
+
}
|
|
95
|
+
if (s[i] !== quote) {
|
|
96
|
+
throw new Error(`invalid highlight \`{${inner}}\` — unterminated label`);
|
|
97
|
+
}
|
|
98
|
+
i++;
|
|
99
|
+
label = value;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
annotations.push(label ? { lines, label } : { lines });
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
return annotations;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
export function parseHighlightSpec(inner: string): HighlightSpec {
|
|
109
|
+
const annotations = parseHighlightMeta(inner);
|
|
110
|
+
const lines = [...new Set(annotations.flatMap((a) => a.lines))];
|
|
111
|
+
const labels: Record<number, string> = {};
|
|
112
|
+
for (const annotation of annotations) {
|
|
113
|
+
if (annotation.label && annotation.lines[0] != null) {
|
|
114
|
+
labels[annotation.lines[0]] = annotation.label;
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
return { lines, labels };
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/** Inverse of `parseHighlightSpec`: `{ lines: [1,2,3,7], labels: { 1: 'a' } }` → `1-3="a",7`. */
|
|
121
|
+
export function formatHighlightSpec(spec: HighlightSpec): string {
|
|
122
|
+
const lines = [...new Set(spec.lines)].sort((a, b) => a - b);
|
|
123
|
+
const groups: { start: number; end: number }[] = [];
|
|
124
|
+
for (const line of lines) {
|
|
125
|
+
const last = groups[groups.length - 1];
|
|
126
|
+
if (last && line === last.end + 1 && !spec.labels[line]) {
|
|
127
|
+
last.end = line;
|
|
128
|
+
} else {
|
|
129
|
+
groups.push({ start: line, end: line });
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
return groups
|
|
133
|
+
.map(({ start, end }) => {
|
|
134
|
+
const range = start === end ? String(start) : `${start}-${end}`;
|
|
135
|
+
const label = spec.labels[start];
|
|
136
|
+
return label ? `${range}="${label.replace(/["\\]/g, '\\$&')}"` : range;
|
|
137
|
+
})
|
|
138
|
+
.join(',');
|
|
139
|
+
}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
const BARE_IMPORT_RE =
|
|
2
|
+
/(?:import|export)\s[^'"]*?from\s+['"]([^'"./][^'"]*)['"]|import\s*\(?\s*['"]([^'"./][^'"]*)['"]/g;
|
|
3
|
+
|
|
4
|
+
/** Bare (package) specifiers a source file imports, e.g. `react`, `@scope/pkg/sub`. */
|
|
5
|
+
export function bareImports(source: string): string[] {
|
|
6
|
+
const found = new Set<string>();
|
|
7
|
+
for (const match of source.matchAll(BARE_IMPORT_RE)) {
|
|
8
|
+
const specifier = match[1] ?? match[2];
|
|
9
|
+
if (specifier && !specifier.startsWith('node:')) found.add(specifier);
|
|
10
|
+
}
|
|
11
|
+
return [...found];
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
/** `@scope/pkg/sub` → `@scope/pkg`, `pkg/sub` → `pkg`. */
|
|
15
|
+
export function packageName(specifier: string): string {
|
|
16
|
+
const parts = specifier.split('/');
|
|
17
|
+
return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
|
|
18
|
+
}
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
export {
|
|
2
|
+
applySourceReplacements,
|
|
3
|
+
dedent,
|
|
4
|
+
extractCodeMarkers,
|
|
5
|
+
listRegionNames,
|
|
6
|
+
sliceRegion,
|
|
7
|
+
stripCodeMarkers,
|
|
8
|
+
type CodeWithMarkers,
|
|
9
|
+
type SlicedRange,
|
|
10
|
+
} from './regions.ts';
|
|
11
|
+
export {
|
|
12
|
+
HEIGHT_META_RE,
|
|
13
|
+
HIGHLIGHT_META_RE,
|
|
14
|
+
LINES_META_RE,
|
|
15
|
+
ORIGINAL_LINES_META_RE,
|
|
16
|
+
formatHighlightSpec,
|
|
17
|
+
parseHighlightMeta,
|
|
18
|
+
parseHighlightSpec,
|
|
19
|
+
type HighlightAnnotation,
|
|
20
|
+
type HighlightSpec,
|
|
21
|
+
} from './highlightSpec.ts';
|
|
22
|
+
export { formatLineRanges, parseLineRanges } from './lineRanges.ts';
|
|
23
|
+
export {
|
|
24
|
+
DEMO_HEIGHTS,
|
|
25
|
+
parseDemoHeight,
|
|
26
|
+
type DemoHeight,
|
|
27
|
+
type DemoHeightName,
|
|
28
|
+
type DemoHeights,
|
|
29
|
+
} from './heights.ts';
|
|
30
|
+
export {
|
|
31
|
+
DEFAULT_CODE_THEMES,
|
|
32
|
+
dirnameOf,
|
|
33
|
+
fenceTransformers,
|
|
34
|
+
highlightCode,
|
|
35
|
+
joinPath,
|
|
36
|
+
langForFile,
|
|
37
|
+
matchImportedFile,
|
|
38
|
+
transformerHeightMeta,
|
|
39
|
+
transformerImportFileLinks,
|
|
40
|
+
transformerLineHighlight,
|
|
41
|
+
transformerLineNumbers,
|
|
42
|
+
type CodeThemes,
|
|
43
|
+
type HighlightOptions,
|
|
44
|
+
} from './shiki.ts';
|
|
45
|
+
export { collectDemoFiles, RESOLVE_EXTENSIONS, type DemoSourceFile } from './demoFiles.ts';
|
|
46
|
+
export { bareImports, packageName } from './imports.ts';
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
/** Expands `"1-3,7"` into `[1, 2, 3, 7]` (1-based). */
|
|
2
|
+
export function parseLineRanges(spec: string): number[] {
|
|
3
|
+
const lines: number[] = [];
|
|
4
|
+
for (const part of spec.split(',')) {
|
|
5
|
+
const token = part.trim();
|
|
6
|
+
if (!token) continue;
|
|
7
|
+
const [start, end = start] = token.split('-').map((n) => Number(n.trim()));
|
|
8
|
+
if (!Number.isFinite(start) || !Number.isFinite(end)) continue;
|
|
9
|
+
for (let line = start; line <= end; line++) lines.push(line);
|
|
10
|
+
}
|
|
11
|
+
return lines;
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
/** Compacts `[1, 2, 3, 7]` into `"1-3,7"`. */
|
|
15
|
+
export function formatLineRanges(lines: number[]): string {
|
|
16
|
+
if (!lines.length) return '';
|
|
17
|
+
const parts: string[] = [];
|
|
18
|
+
let start = lines[0];
|
|
19
|
+
let prev = lines[0];
|
|
20
|
+
for (let i = 1; i < lines.length; i++) {
|
|
21
|
+
const n = lines[i];
|
|
22
|
+
if (n === prev + 1) {
|
|
23
|
+
prev = n;
|
|
24
|
+
continue;
|
|
25
|
+
}
|
|
26
|
+
parts.push(start === prev ? String(start) : `${start}-${prev}`);
|
|
27
|
+
start = prev = n;
|
|
28
|
+
}
|
|
29
|
+
parts.push(start === prev ? String(start) : `${start}-${prev}`);
|
|
30
|
+
return parts.join(',');
|
|
31
|
+
}
|
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
import type { HighlightSpec } from './highlightSpec.ts';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Source preparation for docs fences:
|
|
5
|
+
*
|
|
6
|
+
* - `sliceRegion` extracts a VS Code / fumadocs `#region name` block (`region="name"`).
|
|
7
|
+
* - `extractCodeMarkers` strips `#highlight` / `#region` marker comments and
|
|
8
|
+
* returns the lines they highlight.
|
|
9
|
+
*/
|
|
10
|
+
|
|
11
|
+
export type SlicedRange = {
|
|
12
|
+
source: string;
|
|
13
|
+
/** 1-based original file line numbers of the displayed lines. */
|
|
14
|
+
originalLines: number[];
|
|
15
|
+
};
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* VS Code–style region markers, adapted from fumadocs / VitePress.
|
|
19
|
+
* https://github.com/fuma-nama/fumadocs (remark-include)
|
|
20
|
+
*/
|
|
21
|
+
const REGION_MARKERS: { start: RegExp; end: RegExp }[] = [
|
|
22
|
+
{
|
|
23
|
+
start: /^\s*\/\/\s*#?region\b\s*(.*?)\s*$/,
|
|
24
|
+
end: /^\s*\/\/\s*#?endregion\b\s*(.*?)\s*$/,
|
|
25
|
+
},
|
|
26
|
+
{
|
|
27
|
+
start: /^\s*<!--\s*#?region\b\s*(.*?)\s*-->/,
|
|
28
|
+
end: /^\s*<!--\s*#?endregion\b\s*(.*?)\s*-->/,
|
|
29
|
+
},
|
|
30
|
+
{
|
|
31
|
+
start: /^\s*\{?\/\*\s*#region\b\s*(.*?)\s*\*\/\}?/,
|
|
32
|
+
end: /^\s*\{?\/\*\s*#endregion\b\s*(.*?)\s*\*\/\}?/,
|
|
33
|
+
},
|
|
34
|
+
{
|
|
35
|
+
start: /^\s*#[rR]egion\b\s*(.*?)\s*$/,
|
|
36
|
+
end: /^\s*#[eE]nd ?[rR]egion\b\s*(.*?)\s*$/,
|
|
37
|
+
},
|
|
38
|
+
{
|
|
39
|
+
start: /^\s*#\s*#?region\b\s*(.*?)\s*$/,
|
|
40
|
+
end: /^\s*#\s*#?endregion\b\s*(.*?)\s*$/,
|
|
41
|
+
},
|
|
42
|
+
{
|
|
43
|
+
start: /^\s*(?:--|::|@?REM)\s*#region\b\s*(.*?)\s*$/,
|
|
44
|
+
end: /^\s*(?:--|::|@?REM)\s*#endregion\b\s*(.*?)\s*$/,
|
|
45
|
+
},
|
|
46
|
+
{
|
|
47
|
+
start: /^\s*#pragma\s+region\b\s*(.*?)\s*$/,
|
|
48
|
+
end: /^\s*#pragma\s+endregion\b\s*(.*?)\s*$/,
|
|
49
|
+
},
|
|
50
|
+
{
|
|
51
|
+
start: /^\s*\(\*\s*#region\b\s*(.*?)\s*\*\)/,
|
|
52
|
+
end: /^\s*\(\*\s*#endregion\b\s*(.*?)\s*\*\)/,
|
|
53
|
+
},
|
|
54
|
+
];
|
|
55
|
+
|
|
56
|
+
export function dedent(lines: string[]): string {
|
|
57
|
+
const indents = lines
|
|
58
|
+
.filter((line) => line.trim())
|
|
59
|
+
.map((line) => /^[ \t]*/.exec(line)![0].length);
|
|
60
|
+
const minIndent = indents.length ? Math.min(...indents) : 0;
|
|
61
|
+
return lines.map((line) => line.slice(minIndent)).join('\n');
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
export function listRegionNames(source: string): string[] {
|
|
65
|
+
const names = new Set<string>();
|
|
66
|
+
for (const line of source.split('\n')) {
|
|
67
|
+
for (const re of REGION_MARKERS) {
|
|
68
|
+
const match = re.start.exec(line);
|
|
69
|
+
if (match?.[1]) names.add(match[1]);
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
return [...names];
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
function extractNamedRegion(source: string, regionName: string): SlicedRange | null {
|
|
76
|
+
const all = source.split('\n');
|
|
77
|
+
for (let i = 0; i < all.length; i++) {
|
|
78
|
+
for (const re of REGION_MARKERS) {
|
|
79
|
+
let match = re.start.exec(all[i]);
|
|
80
|
+
if (match?.[1] !== regionName) continue;
|
|
81
|
+
let depth = 1;
|
|
82
|
+
const extractedLines: string[] = [];
|
|
83
|
+
const originalLines: number[] = [];
|
|
84
|
+
for (let j = i + 1; j < all.length; j++) {
|
|
85
|
+
match = re.start.exec(all[j]);
|
|
86
|
+
if (match) {
|
|
87
|
+
depth++;
|
|
88
|
+
continue;
|
|
89
|
+
}
|
|
90
|
+
match = re.end.exec(all[j]);
|
|
91
|
+
if (match) {
|
|
92
|
+
if (match[1] === regionName) {
|
|
93
|
+
depth = 0;
|
|
94
|
+
} else if (match[1] === '') {
|
|
95
|
+
depth--;
|
|
96
|
+
} else {
|
|
97
|
+
continue;
|
|
98
|
+
}
|
|
99
|
+
if (depth > 0) continue;
|
|
100
|
+
return { source: dedent(extractedLines), originalLines };
|
|
101
|
+
}
|
|
102
|
+
extractedLines.push(all[j]);
|
|
103
|
+
originalLines.push(j + 1);
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
return null;
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/**
|
|
111
|
+
* Returns the displayed source for `region="name"` plus the original file line
|
|
112
|
+
* numbers (so a `lines` gutter can keep showing those). Throws with the list
|
|
113
|
+
* of known regions when the name doesn't exist.
|
|
114
|
+
*/
|
|
115
|
+
export function sliceRegion(source: string, spec: string, context: string): SlicedRange {
|
|
116
|
+
const name = spec.trim();
|
|
117
|
+
if (!name) throw new Error(`${context}: \`region\` is empty`);
|
|
118
|
+
|
|
119
|
+
const extracted = extractNamedRegion(source, name);
|
|
120
|
+
if (!extracted) {
|
|
121
|
+
const known = listRegionNames(source);
|
|
122
|
+
const hint = known.length
|
|
123
|
+
? ` (known regions: ${known.map((n) => `"${n}"`).join(', ')})`
|
|
124
|
+
: ' (no `#region` markers in the file)';
|
|
125
|
+
throw new Error(
|
|
126
|
+
`${context}: \`region="${spec}"\` — region "${name}" not found${hint}. ` +
|
|
127
|
+
`Mark it with \`//#region ${name}\` … \`//#endregion\``,
|
|
128
|
+
);
|
|
129
|
+
}
|
|
130
|
+
return extracted;
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/** Whole-line `// #highlight label`, `/* #highlight label *\/` or `{/* #highlight label *\/}`. */
|
|
134
|
+
const HIGHLIGHT_START_RE = /^\s*(?:\/\/\s*#highlight\b(.*)|\{?\/\*\s*#highlight\b(.*?)\*\/\}?)\s*$/;
|
|
135
|
+
const HIGHLIGHT_END_RE = /^\s*(?:\/\/\s*#endhighlight\b.*|\{?\/\*\s*#endhighlight\b.*?\*\/\}?)\s*$/;
|
|
136
|
+
/** Trailing `code // #highlight label` (or a `/* … *\/` / `{/* … *\/}` comment) after code. */
|
|
137
|
+
const HIGHLIGHT_INLINE_RE =
|
|
138
|
+
/^(.*?\S)\s*(?:\/\/\s*#highlight\b(.*)|\{\/\*\s*#highlight\b(.*?)\*\/\}|\/\*\s*#highlight\b(.*?)\*\/)\s*$/;
|
|
139
|
+
|
|
140
|
+
function isRegionMarker(line: string): boolean {
|
|
141
|
+
return REGION_MARKERS.some((re) => re.start.test(line) || re.end.test(line));
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
export type CodeWithMarkers = SlicedRange & {
|
|
145
|
+
/** Displayed (1-based) lines marked with `#highlight`, labels on the first line of each block. */
|
|
146
|
+
highlight: HighlightSpec;
|
|
147
|
+
};
|
|
148
|
+
|
|
149
|
+
/**
|
|
150
|
+
* Strips marker comments from a snippet and returns the lines they highlight.
|
|
151
|
+
*
|
|
152
|
+
* - `// #highlight label` … `// #endhighlight` highlights the lines in between.
|
|
153
|
+
* Without a closing `#endhighlight` (before the next `#highlight`), only the
|
|
154
|
+
* next non-blank line is highlighted.
|
|
155
|
+
* With a label, the opening marker becomes an empty highlighted line that
|
|
156
|
+
* shows the label; without one it is removed.
|
|
157
|
+
* - `code // #highlight label` highlights that single line.
|
|
158
|
+
* - `/* … *\/` and `{/* … *\/}` (JSX children) work for both forms.
|
|
159
|
+
* - `#region` / `#endregion` lines are dropped, so full-file views don't show them.
|
|
160
|
+
*
|
|
161
|
+
* `originalLines` (from `sliceRegion`) is kept in step with the removed lines.
|
|
162
|
+
*/
|
|
163
|
+
export function extractCodeMarkers(
|
|
164
|
+
source: string,
|
|
165
|
+
context: string,
|
|
166
|
+
originalLines?: number[],
|
|
167
|
+
): CodeWithMarkers {
|
|
168
|
+
const input = source.split('\n');
|
|
169
|
+
const inputLines = originalLines ?? input.map((_, index) => index + 1);
|
|
170
|
+
const kept: string[] = [];
|
|
171
|
+
const keptLines: number[] = [];
|
|
172
|
+
const highlight: HighlightSpec = { lines: [], labels: {} };
|
|
173
|
+
/** `nextLineOnly`: no `#endhighlight` follows, so the block ends after the next non-blank line. */
|
|
174
|
+
let block: { fileLine: number; startsAt: number; nextLineOnly: boolean } | null = null;
|
|
175
|
+
|
|
176
|
+
const mark = (label: string) => {
|
|
177
|
+
const line = kept.length;
|
|
178
|
+
if (!highlight.lines.includes(line)) highlight.lines.push(line);
|
|
179
|
+
if (label && !highlight.labels[line]) highlight.labels[line] = label;
|
|
180
|
+
};
|
|
181
|
+
|
|
182
|
+
const hasClosingMarker = (startIndex: number) => {
|
|
183
|
+
for (let index = startIndex + 1; index < input.length; index++) {
|
|
184
|
+
if (HIGHLIGHT_END_RE.test(input[index])) return true;
|
|
185
|
+
if (HIGHLIGHT_START_RE.test(input[index])) return false;
|
|
186
|
+
}
|
|
187
|
+
return false;
|
|
188
|
+
};
|
|
189
|
+
|
|
190
|
+
for (let index = 0; index < input.length; index++) {
|
|
191
|
+
const text = input[index];
|
|
192
|
+
const fileLine = inputLines[index];
|
|
193
|
+
const start = HIGHLIGHT_START_RE.exec(text);
|
|
194
|
+
if (start) {
|
|
195
|
+
// A block with an `#endhighlight` never sees another `#highlight` first (see hasClosingMarker).
|
|
196
|
+
if (block) {
|
|
197
|
+
throw new Error(
|
|
198
|
+
`${context}: the \`#highlight\` on line ${block.fileLine} has no code line before the \`#highlight\` on line ${fileLine}`,
|
|
199
|
+
);
|
|
200
|
+
}
|
|
201
|
+
const label = (start[1] ?? start[2] ?? '').trim();
|
|
202
|
+
if (label) {
|
|
203
|
+
// the label row keeps the marker's indentation, so the label lines up with the block
|
|
204
|
+
kept.push(/^\s*/.exec(text)![0]);
|
|
205
|
+
keptLines.push(fileLine);
|
|
206
|
+
mark(label);
|
|
207
|
+
}
|
|
208
|
+
block = { fileLine, startsAt: kept.length + 1, nextLineOnly: !hasClosingMarker(index) };
|
|
209
|
+
continue;
|
|
210
|
+
}
|
|
211
|
+
if (HIGHLIGHT_END_RE.test(text)) {
|
|
212
|
+
if (!block) {
|
|
213
|
+
throw new Error(`${context}: \`#endhighlight\` on line ${fileLine} has no matching \`#highlight\``);
|
|
214
|
+
}
|
|
215
|
+
if (kept.length < block.startsAt) {
|
|
216
|
+
throw new Error(`${context}: the \`#highlight\` block on line ${block.fileLine} is empty`);
|
|
217
|
+
}
|
|
218
|
+
block = null;
|
|
219
|
+
continue;
|
|
220
|
+
}
|
|
221
|
+
if (isRegionMarker(text)) continue;
|
|
222
|
+
|
|
223
|
+
const inline = HIGHLIGHT_INLINE_RE.exec(text);
|
|
224
|
+
kept.push(inline ? inline[1] : text);
|
|
225
|
+
keptLines.push(fileLine);
|
|
226
|
+
if (inline) mark((inline[2] ?? inline[3] ?? inline[4] ?? '').trim());
|
|
227
|
+
if (block) {
|
|
228
|
+
mark('');
|
|
229
|
+
if (block.nextLineOnly && text.trim()) block = null;
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
if (block) {
|
|
234
|
+
throw new Error(`${context}: the \`#highlight\` on line ${block.fileLine} has no code line after it`);
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
return { source: dedent(kept), originalLines: keptLines, highlight };
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
/**
|
|
241
|
+
* Removes every marker comment (`#highlight`, `#endhighlight`, trailing
|
|
242
|
+
* `// #highlight`, `#region` lines) without the empty label rows that
|
|
243
|
+
* `extractCodeMarkers` keeps for display: the code to copy, edit and fork.
|
|
244
|
+
*/
|
|
245
|
+
export function stripCodeMarkers(source: string): string {
|
|
246
|
+
const kept: string[] = [];
|
|
247
|
+
for (const line of source.split('\n')) {
|
|
248
|
+
if (HIGHLIGHT_START_RE.test(line) || HIGHLIGHT_END_RE.test(line) || isRegionMarker(line)) continue;
|
|
249
|
+
const inline = HIGHLIGHT_INLINE_RE.exec(line);
|
|
250
|
+
kept.push(inline ? inline[1] : line);
|
|
251
|
+
}
|
|
252
|
+
return dedent(kept);
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
/**
|
|
256
|
+
* Applies literal `search → replacement` pairs to source shown in the docs
|
|
257
|
+
* (e.g. `process.env.API_URL` → `"https://…"`), so displayed, edited and
|
|
258
|
+
* forked code runs without the docs build's `define`s.
|
|
259
|
+
*/
|
|
260
|
+
export function applySourceReplacements(
|
|
261
|
+
source: string,
|
|
262
|
+
replacements: Record<string, string> | undefined,
|
|
263
|
+
): string {
|
|
264
|
+
if (!replacements) return source;
|
|
265
|
+
let result = source;
|
|
266
|
+
for (const [search, replacement] of Object.entries(replacements)) {
|
|
267
|
+
result = result.split(search).join(replacement);
|
|
268
|
+
}
|
|
269
|
+
return result;
|
|
270
|
+
}
|