@thedatagrid/docs-kit 0.6.1 → 0.7.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 +6 -0
- package/README.md +18 -2
- package/dist/react/Terminal.d.ts +17 -0
- package/dist/react/Terminal.d.ts.map +1 -0
- package/dist/react/Terminal.js +33 -0
- package/dist/react/Terminal.js.map +1 -0
- package/dist/react/index.d.ts +1 -0
- package/dist/react/index.d.ts.map +1 -1
- package/dist/react/index.js +1 -0
- package/dist/react/index.js.map +1 -1
- package/dist/react/styles.css +45 -0
- package/dist/remark/index.d.ts +1 -0
- package/dist/remark/index.d.ts.map +1 -1
- package/dist/remark/index.js +1 -0
- package/dist/remark/index.js.map +1 -1
- package/dist/remark/remarkTerminalFences.d.ts +24 -0
- package/dist/remark/remarkTerminalFences.d.ts.map +1 -0
- package/dist/remark/remarkTerminalFences.js +43 -0
- package/dist/remark/remarkTerminalFences.js.map +1 -0
- package/package.json +1 -1
- package/src/react/Terminal.tsx +76 -0
- package/src/react/index.ts +1 -0
- package/src/react/styles.css +45 -0
- package/src/remark/index.ts +1 -0
- package/src/remark/remarkTerminalFences.ts +56 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,11 @@
|
|
|
1
1
|
# @thedatagrid/docs-kit
|
|
2
2
|
|
|
3
|
+
## 0.7.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 29d9172: Shell fences as a terminal with a copy button: `remarkTerminalFences` (`/remark`) turns `bash` / `sh` fences into `<Terminal>` (`/react`), with an optional `$` prompt that is never selected or copied.
|
|
8
|
+
|
|
3
9
|
## 0.6.1
|
|
4
10
|
|
|
5
11
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -21,10 +21,10 @@ One package, with subpath exports:
|
|
|
21
21
|
| Subpath | What |
|
|
22
22
|
|---|---|
|
|
23
23
|
| `/code` | regions, highlight markers, shiki transformers and `highlightCode`, demo file collection |
|
|
24
|
-
| `/remark` | `remarkDemoFences`: `file=` / `region=` / `live` / `lines` / `height` fences; `remarkFrameworkLinks`, `remarkFrameworkText` |
|
|
24
|
+
| `/remark` | `remarkDemoFences`: `file=` / `region=` / `live` / `lines` / `height` fences; `remarkTerminalFences`: `bash` / `sh` fences as a terminal; `remarkFrameworkLinks`, `remarkFrameworkText` |
|
|
25
25
|
| `/demos` | the demo builder (`buildDemos`, `docs-kit demos` CLI), config types, `compileDemo` |
|
|
26
26
|
| `/demos/client` | browser-side compilers (`browser` worker or `remote`) |
|
|
27
|
-
| `/react` | `Demo` (server component), `DemoShell` (client card), `createDemoComponents` |
|
|
27
|
+
| `/react` | `Demo` (server component), `DemoShell` (client card), `createDemoComponents`, `Terminal` |
|
|
28
28
|
| `/react/styles.css` | the card styles (CSS custom properties) |
|
|
29
29
|
| `/fork` | fork payloads: CodeSandbox for React demos, StackBlitz (Vite) for Vue demos |
|
|
30
30
|
| `/frameworks` | framework routing: path mapping, link and switch targets, sidebar mapping, the stored preference |
|
|
@@ -88,6 +88,22 @@ A `lines` from the defaults only numbers snippets of more than `linesAbove`
|
|
|
88
88
|
lines (default `5`; `0` numbers every snippet). Each file of a live demo is
|
|
89
89
|
counted on its own. A fence that sets `lines` itself is always numbered.
|
|
90
90
|
|
|
91
|
+
### Shell fences
|
|
92
|
+
|
|
93
|
+
`remarkTerminalFences` turns `bash` / `sh` / `shell` / `zsh` fences into
|
|
94
|
+
`<Terminal code>` (from `/react`): a card with a "Terminal" bar and a copy
|
|
95
|
+
button.
|
|
96
|
+
|
|
97
|
+
```js
|
|
98
|
+
remarkTerminalFences({ prompt: true }); // options: langs, prompt, componentName
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
`prompt` shows a `$` before each command (not before blank lines, `#`
|
|
102
|
+
comments or the lines after a trailing `\`). A fence overrides it with
|
|
103
|
+
`prompt` / `prompt=false`, and can set a `title="..."` for the bar. The `$` is
|
|
104
|
+
drawn by CSS, so it is never selected or copied. Change it with
|
|
105
|
+
`--dk-terminal-prompt: '>'`; restyle with the `.dk-terminal*` rules.
|
|
106
|
+
|
|
91
107
|
## Building demos
|
|
92
108
|
|
|
93
109
|
`docs-kit.config.mjs` in the site root:
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
export type TerminalProps = {
|
|
2
|
+
/** The commands, one per line. What the copy button copies. */
|
|
3
|
+
code: string;
|
|
4
|
+
/**
|
|
5
|
+
* A `$` before each command. It's drawn by CSS, so it's never selected or
|
|
6
|
+
* copied. Blank lines, `#` comments and the lines after a trailing `\` get
|
|
7
|
+
* none. MDX passes `"true"` / `"false"`.
|
|
8
|
+
*/
|
|
9
|
+
prompt?: boolean | 'true' | 'false';
|
|
10
|
+
/** Shown in the bar. Default `Terminal`. */
|
|
11
|
+
title?: string;
|
|
12
|
+
};
|
|
13
|
+
/** Lines that start a command: not blank, not a `#` comment, not continuing a `\` line. */
|
|
14
|
+
export declare function terminalCommandLines(code: string): boolean[];
|
|
15
|
+
/** A shell snippet with a copy button: what `remarkTerminalFences` turns `bash` fences into. */
|
|
16
|
+
export declare function Terminal({ code, prompt, title }: TerminalProps): import("react").JSX.Element;
|
|
17
|
+
//# sourceMappingURL=Terminal.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"Terminal.d.ts","sourceRoot":"","sources":["../../src/react/Terminal.tsx"],"names":[],"mappings":"AAIA,MAAM,MAAM,aAAa,GAAG;IAC1B,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;IACpC,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,2FAA2F;AAC3F,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAQ5D;AAED,gGAAgG;AAChG,wBAAgB,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAkB,EAAE,EAAE,aAAa,+BAsC3E"}
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
'use client';
|
|
2
|
+
import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
|
|
3
|
+
import { useEffect, useRef, useState } from 'react';
|
|
4
|
+
/** Lines that start a command: not blank, not a `#` comment, not continuing a `\` line. */
|
|
5
|
+
export function terminalCommandLines(code) {
|
|
6
|
+
let continued = false;
|
|
7
|
+
return code.split('\n').map((line) => {
|
|
8
|
+
const trimmed = line.trim();
|
|
9
|
+
const command = !continued && trimmed !== '' && !trimmed.startsWith('#');
|
|
10
|
+
continued = trimmed.endsWith('\\');
|
|
11
|
+
return command;
|
|
12
|
+
});
|
|
13
|
+
}
|
|
14
|
+
/** A shell snippet with a copy button: what `remarkTerminalFences` turns `bash` fences into. */
|
|
15
|
+
export function Terminal({ code, prompt, title = 'Terminal' }) {
|
|
16
|
+
const showPrompt = prompt === true || prompt === 'true';
|
|
17
|
+
const [copied, setCopied] = useState(false);
|
|
18
|
+
const timer = useRef(undefined);
|
|
19
|
+
useEffect(() => () => window.clearTimeout(timer.current), []);
|
|
20
|
+
const lines = code.split('\n');
|
|
21
|
+
const commands = showPrompt ? terminalCommandLines(code) : null;
|
|
22
|
+
const copy = () => {
|
|
23
|
+
void navigator.clipboard.writeText(code);
|
|
24
|
+
setCopied(true);
|
|
25
|
+
window.clearTimeout(timer.current);
|
|
26
|
+
timer.current = window.setTimeout(() => setCopied(false), 1200);
|
|
27
|
+
};
|
|
28
|
+
return (_jsxs("div", { className: "dk-terminal", translate: "no", children: [_jsxs("div", { className: "dk-terminal-bar", children: [_jsx(TerminalIcon, {}), _jsx("span", { className: "dk-terminal-title", children: title }), _jsx("span", { className: "dk-demo-spacer" }), _jsx("button", { type: "button", className: "dk-demo-action dk-terminal-copy", onClick: copy, "aria-label": "Copy commands", children: copied ? 'copied ✓' : 'copy' })] }), _jsx("pre", { className: "dk-terminal-body", children: _jsx("code", { children: lines.map((line, index) => (_jsxs("span", { className: `dk-terminal-line${commands?.[index] ? ' dk-terminal-line--command' : ''}`, children: [line, index < lines.length - 1 ? '\n' : null] }, index))) }) })] }));
|
|
29
|
+
}
|
|
30
|
+
function TerminalIcon() {
|
|
31
|
+
return (_jsx("svg", { className: "dk-terminal-icon", viewBox: "0 0 16 16", width: "14", height: "14", fill: "none", "aria-hidden": "true", children: _jsx("path", { d: "M3 4.5 6.5 8 3 11.5M8 11.5h5", stroke: "currentColor", strokeWidth: "1.5", strokeLinecap: "round", strokeLinejoin: "round" }) }));
|
|
32
|
+
}
|
|
33
|
+
//# sourceMappingURL=Terminal.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"Terminal.js","sourceRoot":"","sources":["../../src/react/Terminal.tsx"],"names":[],"mappings":"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"}
|
package/dist/react/index.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
export { createDemoComponents, Demo, DemoDescription, DemoTitle, type DemoContext, type DemoProps, } from './Demo.tsx';
|
|
2
2
|
export { DemoShell, type DemoShellFile, type DemoShellProps } from './DemoShell.tsx';
|
|
3
3
|
export { DemoIframe, type DemoIframeHandle } from './DemoIframe.tsx';
|
|
4
|
+
export { Terminal, terminalCommandLines, type TerminalProps } from './Terminal.tsx';
|
|
4
5
|
//# sourceMappingURL=index.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,IAAI,EACJ,eAAe,EACf,SAAS,EACT,KAAK,WAAW,EAChB,KAAK,SAAS,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACrF,OAAO,EAAE,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,IAAI,EACJ,eAAe,EACf,SAAS,EACT,KAAK,WAAW,EAChB,KAAK,SAAS,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACrF,OAAO,EAAE,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,oBAAoB,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC"}
|
package/dist/react/index.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
export { createDemoComponents, Demo, DemoDescription, DemoTitle, } from "./Demo.js";
|
|
2
2
|
export { DemoShell } from "./DemoShell.js";
|
|
3
3
|
export { DemoIframe } from "./DemoIframe.js";
|
|
4
|
+
export { Terminal, terminalCommandLines } from "./Terminal.js";
|
|
4
5
|
//# sourceMappingURL=index.js.map
|
package/dist/react/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,IAAI,EACJ,eAAe,EACf,SAAS,GAGV,MAAM,WAAY,CAAC;AACpB,OAAO,EAAE,SAAS,EAA2C,MAAM,gBAAiB,CAAC;AACrF,OAAO,EAAE,UAAU,EAAyB,MAAM,iBAAkB,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,IAAI,EACJ,eAAe,EACf,SAAS,GAGV,MAAM,WAAY,CAAC;AACpB,OAAO,EAAE,SAAS,EAA2C,MAAM,gBAAiB,CAAC;AACrF,OAAO,EAAE,UAAU,EAAyB,MAAM,iBAAkB,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,oBAAoB,EAAsB,MAAM,eAAgB,CAAC"}
|
package/dist/react/styles.css
CHANGED
|
@@ -556,3 +556,48 @@
|
|
|
556
556
|
white-space: nowrap;
|
|
557
557
|
text-overflow: ellipsis;
|
|
558
558
|
}
|
|
559
|
+
|
|
560
|
+
/* shell snippets (Terminal, from remarkTerminalFences) */
|
|
561
|
+
.dk-terminal {
|
|
562
|
+
margin: 1.25rem 0;
|
|
563
|
+
overflow: hidden;
|
|
564
|
+
border: 1px solid var(--dk-border);
|
|
565
|
+
border-radius: var(--dk-radius);
|
|
566
|
+
background: var(--dk-code-bg);
|
|
567
|
+
color: var(--dk-fg);
|
|
568
|
+
}
|
|
569
|
+
.dk-terminal-bar {
|
|
570
|
+
display: flex;
|
|
571
|
+
align-items: center;
|
|
572
|
+
gap: 8px;
|
|
573
|
+
min-height: 36px;
|
|
574
|
+
padding: 2px 6px 2px 14px;
|
|
575
|
+
border-bottom: 1px solid var(--dk-border);
|
|
576
|
+
background: var(--dk-surface);
|
|
577
|
+
color: var(--dk-muted);
|
|
578
|
+
font-family: var(--dk-font-mono);
|
|
579
|
+
font-size: 12px;
|
|
580
|
+
}
|
|
581
|
+
.dk-terminal-icon {
|
|
582
|
+
flex: none;
|
|
583
|
+
}
|
|
584
|
+
.dk-terminal-body {
|
|
585
|
+
margin: 0;
|
|
586
|
+
padding: 12px 18px;
|
|
587
|
+
overflow-x: auto;
|
|
588
|
+
background: none;
|
|
589
|
+
font-family: var(--dk-font-mono);
|
|
590
|
+
font-size: var(--dk-code-font-size);
|
|
591
|
+
line-height: var(--dk-code-line-height);
|
|
592
|
+
}
|
|
593
|
+
.dk-terminal-body code {
|
|
594
|
+
all: unset;
|
|
595
|
+
white-space: pre;
|
|
596
|
+
}
|
|
597
|
+
/* the prompt is generated content: never selected, never copied */
|
|
598
|
+
.dk-terminal-line--command::before {
|
|
599
|
+
content: var(--dk-terminal-prompt, '$');
|
|
600
|
+
margin-right: 1ch;
|
|
601
|
+
color: var(--dk-faint);
|
|
602
|
+
user-select: none;
|
|
603
|
+
}
|
package/dist/remark/index.d.ts
CHANGED
|
@@ -2,4 +2,5 @@ export { remarkDemoFences, type FenceInfo, type RemarkDemoFencesOptions } from '
|
|
|
2
2
|
export { applyFenceDefaults, DEFAULT_LINES_ABOVE, parseFenceMeta, type FenceDefaults, type FenceProps, } from './meta.ts';
|
|
3
3
|
export { FALLBACK_LINK_ATTRIBUTE, remarkFrameworkLinks, type RemarkFrameworkLinksOptions, } from './remarkFrameworkLinks.ts';
|
|
4
4
|
export { remarkFrameworkText, type RemarkFrameworkTextOptions } from './remarkFrameworkText.ts';
|
|
5
|
+
export { remarkTerminalFences, type RemarkTerminalFencesOptions } from './remarkTerminalFences.ts';
|
|
5
6
|
//# sourceMappingURL=index.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/remark/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,SAAS,EAAE,KAAK,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AACvG,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,UAAU,GAChB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,KAAK,2BAA2B,GACjC,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,mBAAmB,EAAE,KAAK,0BAA0B,EAAE,MAAM,0BAA0B,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/remark/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,SAAS,EAAE,KAAK,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AACvG,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,UAAU,GAChB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,KAAK,2BAA2B,GACjC,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,mBAAmB,EAAE,KAAK,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAChG,OAAO,EAAE,oBAAoB,EAAE,KAAK,2BAA2B,EAAE,MAAM,2BAA2B,CAAC"}
|
package/dist/remark/index.js
CHANGED
|
@@ -2,4 +2,5 @@ export { remarkDemoFences } from "./remarkDemoFences.js";
|
|
|
2
2
|
export { applyFenceDefaults, DEFAULT_LINES_ABOVE, parseFenceMeta, } from "./meta.js";
|
|
3
3
|
export { FALLBACK_LINK_ATTRIBUTE, remarkFrameworkLinks, } from "./remarkFrameworkLinks.js";
|
|
4
4
|
export { remarkFrameworkText } from "./remarkFrameworkText.js";
|
|
5
|
+
export { remarkTerminalFences } from "./remarkTerminalFences.js";
|
|
5
6
|
//# sourceMappingURL=index.js.map
|
package/dist/remark/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/remark/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAgD,MAAM,uBAAuB,CAAC;AACvG,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,GAGf,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,uBAAuB,EACvB,oBAAoB,GAErB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,mBAAmB,EAAmC,MAAM,0BAA0B,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/remark/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAgD,MAAM,uBAAuB,CAAC;AACvG,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,GAGf,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,uBAAuB,EACvB,oBAAoB,GAErB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,mBAAmB,EAAmC,MAAM,0BAA0B,CAAC;AAChG,OAAO,EAAE,oBAAoB,EAAoC,MAAM,2BAA2B,CAAC"}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
export type RemarkTerminalFencesOptions = {
|
|
2
|
+
/** Fence languages that render as a terminal. Default `['bash', 'sh', 'shell', 'zsh']`. */
|
|
3
|
+
langs?: string[];
|
|
4
|
+
/**
|
|
5
|
+
* Show a `$` prompt before each command. A fence overrides it with `prompt`
|
|
6
|
+
* / `prompt=false` (or `prompt=off`). Default `false`.
|
|
7
|
+
*/
|
|
8
|
+
prompt?: boolean;
|
|
9
|
+
/** MDX component the fences become. Default `Terminal`. */
|
|
10
|
+
componentName?: string;
|
|
11
|
+
};
|
|
12
|
+
/**
|
|
13
|
+
* Remark plugin: shell fences become a terminal card with a copy button.
|
|
14
|
+
*
|
|
15
|
+
* ```bash prompt title="Install"
|
|
16
|
+
* npm i @acme/grid
|
|
17
|
+
* ```
|
|
18
|
+
*
|
|
19
|
+
* becomes `<Terminal code="npm i @acme/grid" prompt="true" title="Install" />`
|
|
20
|
+
* (render it with `Terminal` from `/react`). Fences with `file="..."` or
|
|
21
|
+
* inside a `<Demo>` are left to `remarkDemoFences`.
|
|
22
|
+
*/
|
|
23
|
+
export declare function remarkTerminalFences(options?: RemarkTerminalFencesOptions): () => (tree: any) => void;
|
|
24
|
+
//# sourceMappingURL=remarkTerminalFences.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"remarkTerminalFences.d.ts","sourceRoot":"","sources":["../../src/remark/remarkTerminalFences.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,2BAA2B,GAAG;IACxC,2FAA2F;IAC3F,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,2DAA2D;IAC3D,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAIF;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,2BAAgC,UAK9D,MAAM,GAAG,UAqBxB"}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import { visit } from 'unist-util-visit';
|
|
2
|
+
import { parseFenceMeta } from "./meta.js";
|
|
3
|
+
const DEFAULT_LANGS = ['bash', 'sh', 'shell', 'zsh'];
|
|
4
|
+
/**
|
|
5
|
+
* Remark plugin: shell fences become a terminal card with a copy button.
|
|
6
|
+
*
|
|
7
|
+
* ```bash prompt title="Install"
|
|
8
|
+
* npm i @acme/grid
|
|
9
|
+
* ```
|
|
10
|
+
*
|
|
11
|
+
* becomes `<Terminal code="npm i @acme/grid" prompt="true" title="Install" />`
|
|
12
|
+
* (render it with `Terminal` from `/react`). Fences with `file="..."` or
|
|
13
|
+
* inside a `<Demo>` are left to `remarkDemoFences`.
|
|
14
|
+
*/
|
|
15
|
+
export function remarkTerminalFences(options = {}) {
|
|
16
|
+
const langs = new Set(options.langs ?? DEFAULT_LANGS);
|
|
17
|
+
const componentName = options.componentName ?? 'Terminal';
|
|
18
|
+
const defaultPrompt = options.prompt ?? false;
|
|
19
|
+
return () => (tree) => {
|
|
20
|
+
visit(tree, 'code', (node, index, parent) => {
|
|
21
|
+
if (index == null || !parent || !langs.has(node.lang ?? ''))
|
|
22
|
+
return;
|
|
23
|
+
if (parent.type === 'mdxJsxFlowElement' && parent.name === 'Demo')
|
|
24
|
+
return;
|
|
25
|
+
const props = parseFenceMeta(node.meta || '');
|
|
26
|
+
if ('file' in props)
|
|
27
|
+
return;
|
|
28
|
+
const prompt = props.prompt === undefined ? defaultPrompt : props.prompt === true || !['false', 'off'].includes(props.prompt);
|
|
29
|
+
const attrs = { code: String(node.value ?? '').trimEnd() };
|
|
30
|
+
if (prompt)
|
|
31
|
+
attrs.prompt = 'true';
|
|
32
|
+
if (typeof props.title === 'string')
|
|
33
|
+
attrs.title = props.title;
|
|
34
|
+
parent.children[index] = {
|
|
35
|
+
type: 'mdxJsxFlowElement',
|
|
36
|
+
name: componentName,
|
|
37
|
+
attributes: Object.entries(attrs).map(([name, value]) => ({ type: 'mdxJsxAttribute', name, value })),
|
|
38
|
+
children: [],
|
|
39
|
+
};
|
|
40
|
+
});
|
|
41
|
+
};
|
|
42
|
+
}
|
|
43
|
+
//# sourceMappingURL=remarkTerminalFences.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"remarkTerminalFences.js","sourceRoot":"","sources":["../../src/remark/remarkTerminalFences.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEzC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAc3C,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;AAErD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAAC,UAAuC,EAAE;IAC5E,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,IAAI,aAAa,CAAC,CAAC;IACtD,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,UAAU,CAAC;IAC1D,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,CAAC;IAE9C,OAAO,GAAG,EAAE,CAAC,CAAC,IAAS,EAAE,EAAE;QACzB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,IAAS,EAAE,KAAyB,EAAE,MAAW,EAAE,EAAE;YACxE,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;gBAAE,OAAO;YACpE,IAAI,MAAM,CAAC,IAAI,KAAK,mBAAmB,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM;gBAAE,OAAO;YAC1E,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;YAC9C,IAAI,MAAM,IAAI,KAAK;gBAAE,OAAO;YAE5B,MAAM,MAAM,GACV,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,KAAK,IAAI,IAAI,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YACjH,MAAM,KAAK,GAA2B,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;YACnF,IAAI,MAAM;gBAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC;YAClC,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ;gBAAE,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;YAE/D,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG;gBACvB,IAAI,EAAE,mBAAmB;gBACzB,IAAI,EAAE,aAAa;gBACnB,UAAU,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;gBACpG,QAAQ,EAAE,EAAE;aACb,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@thedatagrid/docs-kit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.0",
|
|
4
4
|
"description": "Docs tooling: type-checked file snippets with regions and highlights, prebuilt and editable live demos for React and Vue, CodeSandbox forks, docs per framework, scripted showcase demos",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
'use client';
|
|
2
|
+
|
|
3
|
+
import { useEffect, useRef, useState } from 'react';
|
|
4
|
+
|
|
5
|
+
export type TerminalProps = {
|
|
6
|
+
/** The commands, one per line. What the copy button copies. */
|
|
7
|
+
code: string;
|
|
8
|
+
/**
|
|
9
|
+
* A `$` before each command. It's drawn by CSS, so it's never selected or
|
|
10
|
+
* copied. Blank lines, `#` comments and the lines after a trailing `\` get
|
|
11
|
+
* none. MDX passes `"true"` / `"false"`.
|
|
12
|
+
*/
|
|
13
|
+
prompt?: boolean | 'true' | 'false';
|
|
14
|
+
/** Shown in the bar. Default `Terminal`. */
|
|
15
|
+
title?: string;
|
|
16
|
+
};
|
|
17
|
+
|
|
18
|
+
/** Lines that start a command: not blank, not a `#` comment, not continuing a `\` line. */
|
|
19
|
+
export function terminalCommandLines(code: string): boolean[] {
|
|
20
|
+
let continued = false;
|
|
21
|
+
return code.split('\n').map((line) => {
|
|
22
|
+
const trimmed = line.trim();
|
|
23
|
+
const command = !continued && trimmed !== '' && !trimmed.startsWith('#');
|
|
24
|
+
continued = trimmed.endsWith('\\');
|
|
25
|
+
return command;
|
|
26
|
+
});
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/** A shell snippet with a copy button: what `remarkTerminalFences` turns `bash` fences into. */
|
|
30
|
+
export function Terminal({ code, prompt, title = 'Terminal' }: TerminalProps) {
|
|
31
|
+
const showPrompt = prompt === true || prompt === 'true';
|
|
32
|
+
const [copied, setCopied] = useState(false);
|
|
33
|
+
const timer = useRef<number | undefined>(undefined);
|
|
34
|
+
useEffect(() => () => window.clearTimeout(timer.current), []);
|
|
35
|
+
|
|
36
|
+
const lines = code.split('\n');
|
|
37
|
+
const commands = showPrompt ? terminalCommandLines(code) : null;
|
|
38
|
+
|
|
39
|
+
const copy = () => {
|
|
40
|
+
void navigator.clipboard.writeText(code);
|
|
41
|
+
setCopied(true);
|
|
42
|
+
window.clearTimeout(timer.current);
|
|
43
|
+
timer.current = window.setTimeout(() => setCopied(false), 1200);
|
|
44
|
+
};
|
|
45
|
+
|
|
46
|
+
return (
|
|
47
|
+
<div className="dk-terminal" translate="no">
|
|
48
|
+
<div className="dk-terminal-bar">
|
|
49
|
+
<TerminalIcon />
|
|
50
|
+
<span className="dk-terminal-title">{title}</span>
|
|
51
|
+
<span className="dk-demo-spacer" />
|
|
52
|
+
<button type="button" className="dk-demo-action dk-terminal-copy" onClick={copy} aria-label="Copy commands">
|
|
53
|
+
{copied ? 'copied ✓' : 'copy'}
|
|
54
|
+
</button>
|
|
55
|
+
</div>
|
|
56
|
+
<pre className="dk-terminal-body">
|
|
57
|
+
<code>
|
|
58
|
+
{lines.map((line, index) => (
|
|
59
|
+
<span key={index} className={`dk-terminal-line${commands?.[index] ? ' dk-terminal-line--command' : ''}`}>
|
|
60
|
+
{line}
|
|
61
|
+
{index < lines.length - 1 ? '\n' : null}
|
|
62
|
+
</span>
|
|
63
|
+
))}
|
|
64
|
+
</code>
|
|
65
|
+
</pre>
|
|
66
|
+
</div>
|
|
67
|
+
);
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
function TerminalIcon() {
|
|
71
|
+
return (
|
|
72
|
+
<svg className="dk-terminal-icon" viewBox="0 0 16 16" width="14" height="14" fill="none" aria-hidden="true">
|
|
73
|
+
<path d="M3 4.5 6.5 8 3 11.5M8 11.5h5" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
|
|
74
|
+
</svg>
|
|
75
|
+
);
|
|
76
|
+
}
|
package/src/react/index.ts
CHANGED
|
@@ -8,3 +8,4 @@ export {
|
|
|
8
8
|
} from './Demo.tsx';
|
|
9
9
|
export { DemoShell, type DemoShellFile, type DemoShellProps } from './DemoShell.tsx';
|
|
10
10
|
export { DemoIframe, type DemoIframeHandle } from './DemoIframe.tsx';
|
|
11
|
+
export { Terminal, terminalCommandLines, type TerminalProps } from './Terminal.tsx';
|
package/src/react/styles.css
CHANGED
|
@@ -556,3 +556,48 @@
|
|
|
556
556
|
white-space: nowrap;
|
|
557
557
|
text-overflow: ellipsis;
|
|
558
558
|
}
|
|
559
|
+
|
|
560
|
+
/* shell snippets (Terminal, from remarkTerminalFences) */
|
|
561
|
+
.dk-terminal {
|
|
562
|
+
margin: 1.25rem 0;
|
|
563
|
+
overflow: hidden;
|
|
564
|
+
border: 1px solid var(--dk-border);
|
|
565
|
+
border-radius: var(--dk-radius);
|
|
566
|
+
background: var(--dk-code-bg);
|
|
567
|
+
color: var(--dk-fg);
|
|
568
|
+
}
|
|
569
|
+
.dk-terminal-bar {
|
|
570
|
+
display: flex;
|
|
571
|
+
align-items: center;
|
|
572
|
+
gap: 8px;
|
|
573
|
+
min-height: 36px;
|
|
574
|
+
padding: 2px 6px 2px 14px;
|
|
575
|
+
border-bottom: 1px solid var(--dk-border);
|
|
576
|
+
background: var(--dk-surface);
|
|
577
|
+
color: var(--dk-muted);
|
|
578
|
+
font-family: var(--dk-font-mono);
|
|
579
|
+
font-size: 12px;
|
|
580
|
+
}
|
|
581
|
+
.dk-terminal-icon {
|
|
582
|
+
flex: none;
|
|
583
|
+
}
|
|
584
|
+
.dk-terminal-body {
|
|
585
|
+
margin: 0;
|
|
586
|
+
padding: 12px 18px;
|
|
587
|
+
overflow-x: auto;
|
|
588
|
+
background: none;
|
|
589
|
+
font-family: var(--dk-font-mono);
|
|
590
|
+
font-size: var(--dk-code-font-size);
|
|
591
|
+
line-height: var(--dk-code-line-height);
|
|
592
|
+
}
|
|
593
|
+
.dk-terminal-body code {
|
|
594
|
+
all: unset;
|
|
595
|
+
white-space: pre;
|
|
596
|
+
}
|
|
597
|
+
/* the prompt is generated content: never selected, never copied */
|
|
598
|
+
.dk-terminal-line--command::before {
|
|
599
|
+
content: var(--dk-terminal-prompt, '$');
|
|
600
|
+
margin-right: 1ch;
|
|
601
|
+
color: var(--dk-faint);
|
|
602
|
+
user-select: none;
|
|
603
|
+
}
|
package/src/remark/index.ts
CHANGED
|
@@ -12,3 +12,4 @@ export {
|
|
|
12
12
|
type RemarkFrameworkLinksOptions,
|
|
13
13
|
} from './remarkFrameworkLinks.ts';
|
|
14
14
|
export { remarkFrameworkText, type RemarkFrameworkTextOptions } from './remarkFrameworkText.ts';
|
|
15
|
+
export { remarkTerminalFences, type RemarkTerminalFencesOptions } from './remarkTerminalFences.ts';
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
import { visit } from 'unist-util-visit';
|
|
2
|
+
|
|
3
|
+
import { parseFenceMeta } from './meta.ts';
|
|
4
|
+
|
|
5
|
+
export type RemarkTerminalFencesOptions = {
|
|
6
|
+
/** Fence languages that render as a terminal. Default `['bash', 'sh', 'shell', 'zsh']`. */
|
|
7
|
+
langs?: string[];
|
|
8
|
+
/**
|
|
9
|
+
* Show a `$` prompt before each command. A fence overrides it with `prompt`
|
|
10
|
+
* / `prompt=false` (or `prompt=off`). Default `false`.
|
|
11
|
+
*/
|
|
12
|
+
prompt?: boolean;
|
|
13
|
+
/** MDX component the fences become. Default `Terminal`. */
|
|
14
|
+
componentName?: string;
|
|
15
|
+
};
|
|
16
|
+
|
|
17
|
+
const DEFAULT_LANGS = ['bash', 'sh', 'shell', 'zsh'];
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* Remark plugin: shell fences become a terminal card with a copy button.
|
|
21
|
+
*
|
|
22
|
+
* ```bash prompt title="Install"
|
|
23
|
+
* npm i @acme/grid
|
|
24
|
+
* ```
|
|
25
|
+
*
|
|
26
|
+
* becomes `<Terminal code="npm i @acme/grid" prompt="true" title="Install" />`
|
|
27
|
+
* (render it with `Terminal` from `/react`). Fences with `file="..."` or
|
|
28
|
+
* inside a `<Demo>` are left to `remarkDemoFences`.
|
|
29
|
+
*/
|
|
30
|
+
export function remarkTerminalFences(options: RemarkTerminalFencesOptions = {}) {
|
|
31
|
+
const langs = new Set(options.langs ?? DEFAULT_LANGS);
|
|
32
|
+
const componentName = options.componentName ?? 'Terminal';
|
|
33
|
+
const defaultPrompt = options.prompt ?? false;
|
|
34
|
+
|
|
35
|
+
return () => (tree: any) => {
|
|
36
|
+
visit(tree, 'code', (node: any, index: number | undefined, parent: any) => {
|
|
37
|
+
if (index == null || !parent || !langs.has(node.lang ?? '')) return;
|
|
38
|
+
if (parent.type === 'mdxJsxFlowElement' && parent.name === 'Demo') return;
|
|
39
|
+
const props = parseFenceMeta(node.meta || '');
|
|
40
|
+
if ('file' in props) return;
|
|
41
|
+
|
|
42
|
+
const prompt =
|
|
43
|
+
props.prompt === undefined ? defaultPrompt : props.prompt === true || !['false', 'off'].includes(props.prompt);
|
|
44
|
+
const attrs: Record<string, string> = { code: String(node.value ?? '').trimEnd() };
|
|
45
|
+
if (prompt) attrs.prompt = 'true';
|
|
46
|
+
if (typeof props.title === 'string') attrs.title = props.title;
|
|
47
|
+
|
|
48
|
+
parent.children[index] = {
|
|
49
|
+
type: 'mdxJsxFlowElement',
|
|
50
|
+
name: componentName,
|
|
51
|
+
attributes: Object.entries(attrs).map(([name, value]) => ({ type: 'mdxJsxAttribute', name, value })),
|
|
52
|
+
children: [],
|
|
53
|
+
};
|
|
54
|
+
});
|
|
55
|
+
};
|
|
56
|
+
}
|