svelte-highlight 7.14.1 → 7.15.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.
@@ -29,6 +29,31 @@ export type HighlightEditableProps = HTMLAttributes<HTMLPreElement> & {
29
29
  */
30
30
  historyLimit?: number;
31
31
 
32
+ /**
33
+ * Rendering engine. `"css-highlights"` (experimental) paints tokens via
34
+ * the CSS Custom Highlight API (`CSS.highlights`) over plain-text line
35
+ * nodes instead of wrapping them in `<span>`s, so a repaint never
36
+ * replaces DOM the caret could be sitting in. Falls back to `"dom"`
37
+ * silently where `CSS.highlights` is unavailable (Chrome 105+,
38
+ * Safari 17.2+, Firefox 140+); check what was actually used with the
39
+ * `resolvedEngine()` method.
40
+ *
41
+ * Colors only: `::highlight()` doesn't support `font-style`/
42
+ * `font-weight`/`text-decoration` across browsers, so bold/italic scopes
43
+ * render plain in this mode.
44
+ * @default "dom"
45
+ */
46
+ engine?: "dom" | "css-highlights";
47
+
48
+ /**
49
+ * Theme CSS from `svelte-highlight/styles/<theme>`, used only in
50
+ * `"css-highlights"` mode to generate `::highlight()` rules. Colors only
51
+ * (`color`/`background-color`); other declarations are dropped.
52
+ * @example
53
+ * import a11yDark from "svelte-highlight/styles/a11y-dark";
54
+ */
55
+ theme?: string;
56
+
32
57
  /**
33
58
  * Color of the focus outline.
34
59
  * @default "#4589ff"
@@ -110,4 +135,10 @@ export default class HighlightEditable extends SvelteComponentTyped<
110
135
 
111
136
  /** Whether a redo step is available. */
112
137
  canRedo(): boolean;
138
+
139
+ /**
140
+ * The engine actually in use: `engine`, or `"dom"` if `"css-highlights"`
141
+ * was requested but `CSS.highlights` is unavailable.
142
+ */
143
+ resolvedEngine(): "dom" | "css-highlights";
113
144
  }
@@ -0,0 +1,154 @@
1
+ <script>
2
+ /**
3
+ * Growing code buffer. Append chunks as they arrive; arbitrary chunk
4
+ * boundaries (mid-token, mid-line) are handled.
5
+ * @type {string}
6
+ */
7
+ export let code = "";
8
+
9
+ /** @type {import("./languages").LanguageType<string>} */
10
+ export let language;
11
+
12
+ /**
13
+ * Stream finished: hides the caret and performs one final full highlight.
14
+ * @type {boolean}
15
+ */
16
+ export let done = false;
17
+
18
+ /**
19
+ * Show a blinking caret at the end of output while `!done`.
20
+ * @type {boolean}
21
+ */
22
+ export let caret = true;
23
+
24
+ /**
25
+ * Keep the container scrolled to the bottom while streaming, unless the
26
+ * user has scrolled away from the bottom.
27
+ * @type {boolean}
28
+ */
29
+ export let autoScroll = false;
30
+
31
+ import hljs from "highlight.js/lib/core";
32
+ import { createEventDispatcher, onMount, tick } from "svelte";
33
+ import { splitLines } from "./split-lines.js";
34
+
35
+ const dispatch = createEventDispatcher();
36
+
37
+ /** @type {HTMLElement} */
38
+ let container;
39
+
40
+ /** @type {string} */
41
+ let highlighted = "";
42
+
43
+ /** @type {string[]} */
44
+ let lines = [];
45
+
46
+ /** @type {ReturnType<typeof requestAnimationFrame> | undefined} */
47
+ let frame;
48
+
49
+ let mounted = false;
50
+
51
+ // Guards against re-dispatching `done` on every reactive re-run while it
52
+ // stays true; resets so a later restart (done set back to `false`) fires
53
+ // it again next time the stream finishes.
54
+ let doneDispatched = false;
55
+
56
+ // Stick to bottom until the user scrolls away from it.
57
+ let stickToBottom = true;
58
+
59
+ function repaint() {
60
+ hljs.registerLanguage(language.name, language.register);
61
+ highlighted = hljs.highlight(code, { language: language.name }).value;
62
+ lines = splitLines(highlighted);
63
+ dispatch("highlight", { highlighted });
64
+
65
+ if (autoScroll) {
66
+ tick().then(() => {
67
+ if (stickToBottom) scrollToBottom();
68
+ });
69
+ }
70
+ }
71
+
72
+ function scrollToBottom() {
73
+ if (container) container.scrollTop = container.scrollHeight;
74
+ }
75
+
76
+ function onScroll() {
77
+ if (!container) return;
78
+ const gap =
79
+ container.scrollHeight - container.scrollTop - container.clientHeight;
80
+ stickToBottom = gap <= 4;
81
+ }
82
+
83
+ function cancelFrame() {
84
+ if (frame != null) {
85
+ cancelAnimationFrame(frame);
86
+ frame = undefined;
87
+ }
88
+ }
89
+
90
+ // Coalesce a burst of chunks within one frame into a single highlight
91
+ // pass; the tab going hidden just pauses the (already-scheduled) frame
92
+ // rather than queuing more work.
93
+ function scheduleRepaint() {
94
+ if (frame != null) return;
95
+ frame = requestAnimationFrame(() => {
96
+ frame = undefined;
97
+ repaint();
98
+ });
99
+ }
100
+
101
+ $: {
102
+ void code;
103
+ void language;
104
+ if (mounted && !done) {
105
+ doneDispatched = false;
106
+ scheduleRepaint();
107
+ } else {
108
+ // SSR / first paint before mount, and the final full highlight once
109
+ // the stream finishes: both render synchronously, no rAF involved.
110
+ cancelFrame();
111
+ repaint();
112
+ if (mounted && !doneDispatched) {
113
+ doneDispatched = true;
114
+ dispatch("done");
115
+ }
116
+ }
117
+ }
118
+
119
+ $: useSplitRendering = mounted && !done;
120
+ $: showCaret = useSplitRendering && caret;
121
+
122
+ onMount(() => {
123
+ mounted = true;
124
+ return cancelFrame;
125
+ });
126
+ </script>
127
+
128
+ <pre bind:this={container} on:scroll={onScroll} {...$$restProps}><code
129
+ class:hljs={true}
130
+ >{#if useSplitRendering}{#each lines as line, i (i)}{#if i > 0}{"\n"}{/if}<span class="highlight-stream-line" data-line={i}>{@html line}</span>{/each}{#if showCaret}<span class="highlight-stream-caret" aria-hidden="true"></span>{/if}{:else}{@html highlighted}{/if}</code></pre>
131
+
132
+ <style>
133
+ .highlight-stream-caret {
134
+ display: inline-block;
135
+ width: var(--caret-width, 0.6em);
136
+ height: var(--caret-height, 1.1em);
137
+ margin-left: var(--caret-gap, 1px);
138
+ vertical-align: text-bottom;
139
+ background: var(--caret-color, currentColor);
140
+ animation: highlight-stream-blink var(--caret-blink, 1s) step-end infinite;
141
+ }
142
+
143
+ @media (prefers-reduced-motion: reduce) {
144
+ .highlight-stream-caret {
145
+ animation: none;
146
+ }
147
+ }
148
+
149
+ @keyframes highlight-stream-blink {
150
+ 50% {
151
+ opacity: 0;
152
+ }
153
+ }
154
+ </style>
@@ -0,0 +1,90 @@
1
+ import type { SvelteComponentTyped } from "svelte";
2
+ import type { HTMLAttributes } from "svelte/elements";
3
+ import type { LanguageType } from "./languages";
4
+
5
+ export type HighlightStreamProps = HTMLAttributes<HTMLPreElement> & {
6
+ /**
7
+ * Growing code buffer. Append chunks as they arrive; arbitrary chunk
8
+ * boundaries (mid-token, mid-line) are handled.
9
+ * @default ""
10
+ */
11
+ code?: string;
12
+
13
+ /**
14
+ * highlight.js language module.
15
+ * Import languages from `svelte-highlight/languages/*`.
16
+ * @example
17
+ * import typescript from "svelte-highlight/languages/typescript";
18
+ */
19
+ language: LanguageType<string>;
20
+
21
+ /**
22
+ * Stream finished: hides the caret and performs one final full highlight.
23
+ * @default false
24
+ */
25
+ done?: boolean;
26
+
27
+ /**
28
+ * Show a blinking caret at the end of output while `!done`.
29
+ * @default true
30
+ */
31
+ caret?: boolean;
32
+
33
+ /**
34
+ * Keep the container scrolled to the bottom while streaming, unless the
35
+ * user has scrolled away from the bottom.
36
+ * @default false
37
+ */
38
+ autoScroll?: boolean;
39
+
40
+ /**
41
+ * Width of the blinking caret.
42
+ * @default "0.6em"
43
+ */
44
+ "--caret-width"?: string;
45
+
46
+ /**
47
+ * Height of the blinking caret.
48
+ * @default "1.1em"
49
+ */
50
+ "--caret-height"?: string;
51
+
52
+ /**
53
+ * Gap between output and the caret.
54
+ * @default "1px"
55
+ */
56
+ "--caret-gap"?: string;
57
+
58
+ /**
59
+ * Color of the blinking caret.
60
+ * @default "currentColor"
61
+ */
62
+ "--caret-color"?: string;
63
+
64
+ /**
65
+ * Duration of one caret blink cycle.
66
+ * @default "1s"
67
+ */
68
+ "--caret-blink"?: string;
69
+ };
70
+
71
+ export type HighlightStreamEvents = {
72
+ highlight: CustomEvent<{
73
+ /**
74
+ * The highlighted HTML as a string.
75
+ * @example "<span>...</span>"
76
+ */
77
+ highlighted: string;
78
+ }>;
79
+
80
+ /**
81
+ * Fires after the final full highlight once `done` is set.
82
+ */
83
+ done: CustomEvent<null>;
84
+ };
85
+
86
+ export default class HighlightStream extends SvelteComponentTyped<
87
+ HighlightStreamProps,
88
+ HighlightStreamEvents,
89
+ Record<string, never>
90
+ > {}
@@ -1,4 +1,29 @@
1
+ <script context="module">
2
+ import { writable } from "svelte/store";
3
+
4
+ const isBrowser = typeof document !== "undefined";
5
+
6
+ // Instances sharing a key queue up in registration order; only the oldest
7
+ // still-mounted instance renders the `<style>`. A store (rather than a
8
+ // plain ref count) means that when that instance unmounts, the remaining
9
+ // subscribers reactively re-derive a new owner instead of the tag being
10
+ // dropped while siblings still need it.
11
+ /** @type {Map<string, import("svelte/store").Writable<symbol[]>>} */
12
+ const registries = new Map();
13
+
14
+ /** @param {string} key */
15
+ function registryFor(key) {
16
+ let registry = registries.get(key);
17
+ if (!registry) {
18
+ registry = writable([]);
19
+ registries.set(key, registry);
20
+ }
21
+ return registry;
22
+ }
23
+ </script>
24
+
1
25
  <script>
26
+ import { onDestroy } from "svelte";
2
27
  import { dualStyle, scopeClassFor, scopeStyle } from "./scoped.js";
3
28
 
4
29
  /**
@@ -25,15 +50,55 @@
25
50
  export let mode = "auto";
26
51
 
27
52
  /** Scope class for prefixed selectors. */
28
- export let scopeClass = scopeClassFor(theme ?? `${light}${dark}`);
53
+ export let scopeClass = undefined;
54
+
55
+ // Captured once: a consumer-supplied scopeClass is honored for the
56
+ // lifetime of the instance instead of being overwritten by the hash below.
57
+ const hasOwnScopeClass = scopeClass !== undefined;
58
+
59
+ $: hasTheme =
60
+ theme !== undefined || (light !== undefined && dark !== undefined);
29
61
 
30
- $: style =
31
- light !== undefined && dark !== undefined
62
+ $: if (!hasOwnScopeClass) {
63
+ scopeClass = scopeClassFor(theme ?? `${light}${dark}`);
64
+ }
65
+
66
+ $: style = hasTheme
67
+ ? light !== undefined && dark !== undefined
32
68
  ? dualStyle(light, dark, scopeClass, mode)
33
- : scopeStyle(theme, scopeClass);
69
+ : scopeStyle(theme, scopeClass)
70
+ : "";
71
+
72
+ const token = Symbol();
73
+ let registeredKey;
74
+ /** @type {import("svelte/store").Writable<symbol[]> | undefined} */
75
+ let registry;
76
+
77
+ function unregister() {
78
+ registry?.update((owners) => owners.filter((owner) => owner !== token));
79
+ }
80
+
81
+ $: {
82
+ const key = style ? `${scopeClass}::${style}` : undefined;
83
+ if (key !== registeredKey) {
84
+ unregister();
85
+ registeredKey = key;
86
+ registry = isBrowser && key !== undefined ? registryFor(key) : undefined;
87
+ registry?.update((owners) => [...owners, token]);
88
+ }
89
+ }
90
+
91
+ $: owners = $registry ?? [];
92
+ $: shouldRender = !isBrowser || owners[0] === token;
93
+
94
+ onDestroy(unregister);
34
95
  </script>
35
96
 
36
- <svelte:head> {@html style} </svelte:head>
97
+ <svelte:head
98
+ >{#if shouldRender}
99
+ {@html style}
100
+ {/if}</svelte:head
101
+ >
37
102
 
38
103
  <div class={scopeClass} {...$$restProps}>
39
104
  <slot {scopeClass} />
@@ -22,7 +22,8 @@
22
22
 
23
23
  $: {
24
24
  hljs.registerLanguage(svelte.name, svelte.register);
25
- highlighted = hljs.highlight(code, { language: svelte.name }).value;
25
+ const source = typeof code === "string" ? code : String(code ?? "");
26
+ highlighted = hljs.highlight(source, { language: svelte.name }).value;
26
27
  }
27
28
  </script>
28
29
 
package/README.md CHANGED
@@ -535,6 +535,22 @@ The component dispatches a `copy` event on success and an `error` event if the c
535
535
  />
536
536
  ```
537
537
 
538
+ ### Transforming copied text
539
+
540
+ Displayed code often carries decoration that shouldn't survive a copy -- shell prompts, REPL markers, diff signs. Pass a `transform` function to strip it before the `copy` function runs; `on:copy` reports the transformed string, not the original `code`.
541
+
542
+ `stripPrompts` and `stripDiffMarkers` cover the common cases and are exported for reuse (compose them for your own `transform` when a block needs both):
543
+
544
+ ```svelte
545
+ <script>
546
+ import { CopyButton, stripPrompts } from "svelte-highlight";
547
+
548
+ const code = "$ npm install\nadded 1 package";
549
+ </script>
550
+
551
+ <CopyButton {code} transform={stripPrompts} />
552
+ ```
553
+
538
554
  ### Custom Button Content
539
555
 
540
556
  Provide custom button content using the default slot to replace the default icons. The slot exposes a `copied` boolean and a `copying` boolean (`true` while an async `copy` is in flight), so you can render a pending state for slow copy functions.
@@ -649,7 +665,7 @@ Use `bind:this` to call methods on the instance.
649
665
  <button on:click={() => editor.clear()}>Clear</button>
650
666
  ```
651
667
 
652
- Available methods: `undo`, `redo`, `focus`, `selectAll`, `insert`, `indent`, `outdent`, `setCode`, `clear`, `getCode`, `canUndo`, and `canRedo`.
668
+ Available methods: `undo`, `redo`, `focus`, `selectAll`, `insert`, `indent`, `outdent`, `setCode`, `clear`, `getCode`, `canUndo`, `canRedo`, and `resolvedEngine`.
653
669
 
654
670
  ### Custom Styles
655
671
 
@@ -664,6 +680,30 @@ Customize the focus outline with the `--outline-color`, `--outline-width`, and `
664
680
  />
665
681
  ```
666
682
 
683
+ ### Experimental: CSS Custom Highlight engine
684
+
685
+ `engine="css-highlights"` paints tokens with the [CSS Custom Highlight API](https://developer.mozilla.org/en-US/docs/Web/API/CSS_Custom_Highlight_API) (`CSS.highlights`, `::highlight()`) instead of wrapping them in `<span>`s. The editable `<code>` stays plain text (one `<span>` per line, reused from the default engine's line structure, but with no per-token spans inside), so a repaint never replaces the DOM the caret is sitting in.
686
+
687
+ Requires Chrome 105+, Safari 17.2+, or Firefox 140+. Where `CSS.highlights` is unavailable, `HighlightEditable` falls back to `engine="dom"` silently; check what actually ran with `editor.resolvedEngine()`.
688
+
689
+ Pass `theme` (the same theme string you'd give `HighlightStyle`) to generate `::highlight()` rules from it. Only `color`/`background-color` convert — `::highlight()` doesn't support `font-style`/`font-weight`/`text-decoration` across browsers, so bold/italic scopes render in plain color.
690
+
691
+ `theme` only covers token colors — you still need `HighlightStyle` (or an injected stylesheet) for the base `.hljs` layout rules (padding, overflow, background), exactly as with the default engine.
692
+
693
+ ```svelte
694
+ <script>
695
+ import { HighlightEditable, HighlightStyle } from "svelte-highlight";
696
+ import typescript from "svelte-highlight/languages/typescript";
697
+ import github from "svelte-highlight/styles/github";
698
+
699
+ let code = "const add = (a: number, b: number) => a + b";
700
+ </script>
701
+
702
+ <HighlightStyle theme={github}>
703
+ <HighlightEditable language={typescript} bind:code engine="css-highlights" theme={github} />
704
+ </HighlightStyle>
705
+ ```
706
+
667
707
  ## Language Targeting
668
708
 
669
709
  All `Highlight` components apply a `data-language` attribute on the codeblock containing the language name.
@@ -1105,9 +1145,55 @@ Set `speed` (milliseconds per character) and pause with `play`. Turn `play` back
1105
1145
 
1106
1146
  With `prefers-reduced-motion`, the full block shows immediately and `on:done` runs right away. Customize the caret with `--caret-width`, `--caret-height`, `--caret-gap`, `--caret-color`, and `--caret-blink`.
1107
1147
 
1148
+ Each tick reveals one already-rendered unit rather than re-rendering the block, so animating stays smooth up to tens of thousands of characters; past that it falls back to the coarser whole-block reveal.
1149
+
1150
+ ## Streaming
1151
+
1152
+ Rendering LLM chat output is the dominant new syntax-highlighting use case: code arrives in arbitrary-sized chunks, mid-token and mid-line, and you don't know the full content up front. `HighlightStream` is built for that -- unlike `Typewriter`, which animates a complete, already-highlighted string and restarts whenever it changes, `HighlightStream` accepts a growing `code` buffer and re-highlights it as chunks arrive.
1153
+
1154
+ Append to `code` as chunks come in; set `done` once the stream ends.
1155
+
1156
+ ```svelte
1157
+ <script>
1158
+ import { HighlightStream } from "svelte-highlight";
1159
+ import typescript from "svelte-highlight/languages/typescript";
1160
+ import github from "svelte-highlight/styles/github";
1161
+
1162
+ let code = "";
1163
+ let done = false;
1164
+
1165
+ // Wire this up to your streaming source (fetch, WebSocket, SSE, ...).
1166
+ async function stream() {
1167
+ for (const chunk of chunks) {
1168
+ code += chunk;
1169
+ await new Promise((r) => setTimeout(r, 30));
1170
+ }
1171
+ done = true;
1172
+ }
1173
+ </script>
1174
+
1175
+ <svelte:head>
1176
+ {@html github}
1177
+ </svelte:head>
1178
+
1179
+ <HighlightStream language={typescript} {code} {done} />
1180
+ ```
1181
+
1182
+ Multiple chunks appended within the same animation frame coalesce into a single highlight pass. Already-rendered lines are diffed and left untouched in the DOM; only lines whose content actually changed are repainted, so a fast-scrolling response only touches its changed suffix (typically the last line). A multi-line construct left open mid-stream -- an unterminated template literal or block comment -- re-tokenizes the lines it spans once the closing delimiter arrives, with no special-casing needed: it falls out of re-highlighting the full buffer on every update.
1183
+
1184
+ A blinking caret marks the end of output while `!done`; setting `done` hides it and performs one final full highlight, so the finished output matches what `Highlight` would render for the same code. `on:done` fires right after that final highlight. Customize the caret with the same `--caret-width`, `--caret-height`, `--caret-gap`, `--caret-color`, and `--caret-blink` variables as `Typewriter`.
1185
+
1186
+ Set `autoScroll` to keep the container pinned to the bottom as output grows -- it stops auto-scrolling as soon as you scroll up, and resumes once you scroll back to the bottom.
1187
+
1188
+ ```svelte
1189
+ <HighlightStream language={typescript} {code} {done} autoScroll style="max-height: 20em; overflow-y: auto;" />
1190
+ ```
1191
+
1192
+ This is O(buffer) per highlighted frame and DOM updates proportional to the changed lines -- fine for chat-sized output up to a few thousand lines, not a virtualized log viewer.
1193
+
1108
1194
  ## Terminal Output
1109
1195
 
1110
- Use `AnsiOutput` to render terminal output that still contains ANSI [SGR](https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters) escape codes. Colors, bold, dim, italic, and underline become styled HTML. The parser is separate from highlight.js, so reach for it with build logs, CLI output, and test runners.
1196
+ Use `AnsiOutput` to render terminal output that still contains ANSI [SGR](https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_(Select_Graphic_Rendition)_parameters) escape codes. Colors, bold, dim, italic, and underline become styled HTML, along with OSC 8 hyperlinks, carriage-return overwrites, and reverse/strikethrough. The parser is separate from highlight.js, so reach for it with build logs, CLI output, and test runners.
1111
1197
 
1112
1198
  ```svelte
1113
1199
  <script>
@@ -1264,6 +1350,7 @@ Arrow keys move between tabs; `Home` and `End` jump to the first and last. The m
1264
1350
  | :--------- | :----------------------------------------- | :------------------------------------------- |
1265
1351
  | code | `string` | N/A (required) |
1266
1352
  | copy | `(code: string) => void \| Promise<void>` | `(code) => navigator.clipboard.writeText(code)` |
1353
+ | transform | `(code: string) => string` | `(code) => code` |
1267
1354
  | timeout | `number` | `2000` |
1268
1355
  | text | `string` | `"Copy"` |
1269
1356
  | copiedText | `string` | `"Copied!"` |
@@ -1272,7 +1359,7 @@ Arrow keys move between tabs; `Home` and `End` jump to the first and last. The m
1272
1359
 
1273
1360
  #### Dispatched Events
1274
1361
 
1275
- - **on:copy**: fired after a successful copy, with `{ code }`
1362
+ - **on:copy**: fired after a successful copy, with `{ code }` -- the `transform`-applied string, not the original `code` prop
1276
1363
  - **on:error**: fired if the copy behavior throws, with `{ error }`
1277
1364
 
1278
1365
  ```svelte
@@ -1408,6 +1495,35 @@ Use `bind:this`, then call `undo()`, `redo()`, `focus()`, `selectAll()`, `insert
1408
1495
  />
1409
1496
  ```
1410
1497
 
1498
+ ### `HighlightStream`
1499
+
1500
+ #### Props
1501
+
1502
+ | Name | Type | Default value |
1503
+ | :--------- | :--------------------------------------------- | :------------- |
1504
+ | code | `string` | `""` |
1505
+ | language | { name: `string`; register: hljs => `object` } | N/A (required) |
1506
+ | done | `boolean` | `false` |
1507
+ | caret | `boolean` | `true` |
1508
+ | autoScroll | `boolean` | `false` |
1509
+
1510
+ `$$restProps` are forwarded to the top-level `pre` element.
1511
+
1512
+ #### Dispatched Events
1513
+
1514
+ - **on:highlight**: fired after each highlight pass, with `{ highlighted }`
1515
+ - **on:done**: fired after the final full highlight once `done` is set
1516
+
1517
+ ```svelte
1518
+ <HighlightStream
1519
+ language={typescript}
1520
+ {code}
1521
+ {done}
1522
+ on:highlight={(e) => console.log(e.detail.highlighted)}
1523
+ on:done={() => console.log("stream finished")}
1524
+ />
1525
+ ```
1526
+
1411
1527
  ### `FileTabs`
1412
1528
 
1413
1529
  #### Props