svelte-highlight 7.11.0 → 7.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (108) hide show
  1. package/AnsiOutput.svelte +193 -0
  2. package/AnsiOutput.svelte.d.ts +112 -0
  3. package/CodeWindow.svelte +110 -0
  4. package/CodeWindow.svelte.d.ts +136 -0
  5. package/CopyButton.svelte +115 -0
  6. package/CopyButton.svelte.d.ts +134 -0
  7. package/FileTabs.svelte +161 -0
  8. package/FileTabs.svelte.d.ts +96 -0
  9. package/Highlight.svelte.d.ts +9 -10
  10. package/HighlightAuto.svelte.d.ts +2 -2
  11. package/HighlightEditable.svelte +385 -0
  12. package/HighlightEditable.svelte.d.ts +113 -0
  13. package/HighlightStyle.svelte +40 -0
  14. package/HighlightStyle.svelte.d.ts +50 -0
  15. package/HighlightSvelte.svelte.d.ts +1 -1
  16. package/LangTag.svelte +10 -1
  17. package/LangTag.svelte.d.ts +3 -3
  18. package/LineNumbers.svelte +18 -6
  19. package/LineNumbers.svelte.d.ts +24 -8
  20. package/README.md +832 -7
  21. package/Typewriter.svelte +238 -0
  22. package/Typewriter.svelte.d.ts +65 -0
  23. package/action.d.ts +20 -0
  24. package/action.js +25 -0
  25. package/ansi.d.ts +36 -0
  26. package/ansi.js +198 -0
  27. package/index.d.ts +12 -0
  28. package/index.js +10 -0
  29. package/langtag.css +1 -0
  30. package/languages/bibtex.d.ts +2 -0
  31. package/languages/bibtex.js +47 -0
  32. package/languages/bicep.d.ts +2 -0
  33. package/languages/bicep.js +72 -0
  34. package/languages/blade.d.ts +2 -0
  35. package/languages/blade.js +56 -0
  36. package/languages/caddy.d.ts +2 -0
  37. package/languages/caddy.js +59 -0
  38. package/languages/cairo.d.ts +2 -0
  39. package/languages/cairo.js +69 -0
  40. package/languages/clarity.d.ts +2 -0
  41. package/languages/clarity.js +55 -0
  42. package/languages/cue.d.ts +2 -0
  43. package/languages/cue.js +76 -0
  44. package/languages/cypher.d.ts +2 -0
  45. package/languages/cypher.js +61 -0
  46. package/languages/d2.d.ts +2 -0
  47. package/languages/d2.js +61 -0
  48. package/languages/dhall.d.ts +2 -0
  49. package/languages/dhall.js +74 -0
  50. package/languages/dotenv.d.ts +2 -0
  51. package/languages/dotenv.js +44 -0
  52. package/languages/fish.d.ts +2 -0
  53. package/languages/fish.js +68 -0
  54. package/languages/gleam.d.ts +2 -0
  55. package/languages/gleam.js +63 -0
  56. package/languages/groq.d.ts +2 -0
  57. package/languages/groq.js +69 -0
  58. package/languages/hcl.d.ts +2 -0
  59. package/languages/hcl.js +84 -0
  60. package/languages/index.d.ts +73 -1
  61. package/languages/index.js +36 -0
  62. package/languages/json5.d.ts +2 -0
  63. package/languages/json5.js +55 -0
  64. package/languages/jsonc.d.ts +2 -0
  65. package/languages/jsonc.js +36 -0
  66. package/languages/jsonnet.d.ts +2 -0
  67. package/languages/jsonnet.js +64 -0
  68. package/languages/liquid.d.ts +2 -0
  69. package/languages/liquid.js +55 -0
  70. package/languages/move.d.ts +2 -0
  71. package/languages/move.js +72 -0
  72. package/languages/nickel.d.ts +2 -0
  73. package/languages/nickel.js +65 -0
  74. package/languages/nushell.d.ts +2 -0
  75. package/languages/nushell.js +77 -0
  76. package/languages/odin.d.ts +2 -0
  77. package/languages/odin.js +78 -0
  78. package/languages/pkl.d.ts +2 -0
  79. package/languages/pkl.js +82 -0
  80. package/languages/prisma.d.ts +2 -0
  81. package/languages/prisma.js +70 -0
  82. package/languages/promql.d.ts +2 -0
  83. package/languages/promql.js +61 -0
  84. package/languages/pug.d.ts +2 -0
  85. package/languages/pug.js +50 -0
  86. package/languages/razor.d.ts +2 -0
  87. package/languages/razor.js +69 -0
  88. package/languages/rescript.d.ts +2 -0
  89. package/languages/rescript.js +71 -0
  90. package/languages/solidity.d.ts +2 -0
  91. package/languages/solidity.js +101 -0
  92. package/languages/starlark.d.ts +2 -0
  93. package/languages/starlark.js +54 -0
  94. package/languages/toml.d.ts +2 -0
  95. package/languages/toml.js +74 -0
  96. package/languages/v.d.ts +2 -0
  97. package/languages/v.js +90 -0
  98. package/languages/vyper.d.ts +2 -0
  99. package/languages/vyper.js +57 -0
  100. package/languages/wgsl.d.ts +2 -0
  101. package/languages/wgsl.js +56 -0
  102. package/languages/zig.d.ts +2 -0
  103. package/languages/zig.js +100 -0
  104. package/load-language.d.ts +9 -0
  105. package/load-language.js +15 -0
  106. package/package.json +1 -1
  107. package/scoped.d.ts +23 -0
  108. package/scoped.js +307 -0
package/README.md CHANGED
@@ -123,6 +123,163 @@ CSS StyleSheets can also be externally linked from a Content Delivery Network (C
123
123
  </svelte:head>
124
124
  ```
125
125
 
126
+ ### Scoping styles
127
+
128
+ Themes target global `.hljs` selectors. Add more than one and the last injected wins. That works when every block on the page shares one theme.
129
+
130
+ Reach for scoped styles when blocks on the same page need different themes: a style gallery, a side-by-side comparison, or a light snippet next to a dark one.
131
+
132
+ Wrap each `Highlight` in `HighlightStyle` to keep a theme on that block:
133
+
134
+ ```svelte
135
+ <script>
136
+ import { Highlight, HighlightStyle } from "svelte-highlight";
137
+ import typescript from "svelte-highlight/languages/typescript";
138
+ import a11yDark from "svelte-highlight/styles/a11y-dark";
139
+ import github from "svelte-highlight/styles/github";
140
+
141
+ const code = "const add = (a: number, b: number) => a + b;";
142
+ </script>
143
+
144
+ <HighlightStyle theme={a11yDark}>
145
+ <Highlight language={typescript} {code} />
146
+ </HighlightStyle>
147
+
148
+ <HighlightStyle theme={github}>
149
+ <Highlight language={typescript} {code} />
150
+ </HighlightStyle>
151
+ ```
152
+
153
+ The component prefixes each selector with a scope class on the wrapper, so the theme only hits markup inside it.
154
+
155
+ `theme` is required. `scopeClass` defaults to a hash of the theme string. Pass your own, or bind it (`bind:scopeClass`) / read it from the slot (`let:scopeClass`).
156
+
157
+ For a page-wide theme, use `{@html theme}` as shown above.
158
+
159
+ ### Dark mode
160
+
161
+ `HighlightStyle` can emit a light and a dark theme together and switch between them. Pass `light` and `dark` instead of `theme`:
162
+
163
+ ```svelte
164
+ <script>
165
+ import { Highlight, HighlightStyle } from "svelte-highlight";
166
+ import typescript from "svelte-highlight/languages/typescript";
167
+ import github from "svelte-highlight/styles/github";
168
+ import githubDark from "svelte-highlight/styles/github-dark";
169
+
170
+ const code = "const add = (a: number, b: number) => a + b;";
171
+ </script>
172
+
173
+ <HighlightStyle light={github} dark={githubDark}>
174
+ <Highlight language={typescript} {code} />
175
+ </HighlightStyle>
176
+ ```
177
+
178
+ The `mode` prop controls how the two themes are switched (default `"auto"`):
179
+
180
+ - `"auto"` — wrap each theme in a `@media (prefers-color-scheme: …)` query so the OS/browser preference decides.
181
+ - `"light"` / `"dark"` — emit only that single theme.
182
+ - any other string — treated as a CSS selector that gates the dark block while light stays the default. Use this to drive theming from a class or attribute on an ancestor, e.g. a manual theme toggle:
183
+
184
+ ```svelte
185
+ <HighlightStyle light={github} dark={githubDark} mode={'[data-theme="dark"]'}>
186
+ <Highlight language={typescript} {code} />
187
+ </HighlightStyle>
188
+ ```
189
+
190
+ Both themes are scoped to the wrapper, so different blocks can use different theme pairs on the same page. When `light` and `dark` are both set they take precedence over `theme`; passing only `theme` keeps the existing single-theme behavior unchanged.
191
+
192
+ ## Styling with CSS variables
193
+
194
+ Every `Highlight` variant forwards `$$restProps` to its top-level element, so you can style the component using CSS variables without resorting to `:global` overrides or `!important`.
195
+
196
+ ```svelte
197
+ <Highlight
198
+ language={typescript}
199
+ {code}
200
+ --border-radius="8px"
201
+ --max-width="40rem"
202
+ />
203
+ ```
204
+
205
+ ### Container variables
206
+
207
+ These apply to the outer container of every component (the `pre` element for `Highlight`, `HighlightAuto`, `HighlightSvelte`, and `LangTag`; the `div` element for `LineNumbers`).
208
+
209
+ | Variable | Description | Default value |
210
+ | :-------------- | :----------------------------------------- | :------------ |
211
+ | --border-radius | Border radius of the container | `0` |
212
+ | --width | Width of the container | `auto` |
213
+ | --max-width | Maximum width of the container | `none` |
214
+ | --overflow-x | Horizontal overflow behavior | `auto` |
215
+ | --overflow-y | Vertical overflow behavior | `auto` |
216
+
217
+ > [!NOTE]
218
+ > Because the container clips its content (`overflow` is not `visible` by default), setting `--border-radius` rounds the visible corners without any extra CSS.
219
+
220
+ ### `LineNumbers` variables
221
+
222
+ | Variable | Description | Default value |
223
+ | :----------------------- | :------------------------------------------------ | :------------------------ |
224
+ | --line-number-color | Text color of the line numbers | `currentColor` |
225
+ | --border-color | Border color of the column of line numbers | `currentColor` |
226
+ | --highlighted-background | Background color of highlighted lines | `rgba(254, 241, 96, 0.2)` |
227
+ | --unhighlighted-opacity | Opacity of un-highlighted lines (focus mode) | `1` |
228
+ | --unhighlighted-filter | CSS filter for un-highlighted lines (focus mode) | `none` |
229
+ | --padding | Fallback padding for `--padding-left` / `--padding-right` | `1em` |
230
+ | --padding-left | Left padding for `td` elements | `var(--padding, 1em)` |
231
+ | --padding-right | Right padding for `td` elements | `var(--padding, 1em)` |
232
+
233
+ ### `CopyButton` variables
234
+
235
+ | Variable | Description | Default value |
236
+ | :------------------- | :----------------------------------- | :------------ |
237
+ | --copy-top | Top offset of the button | `0.5em` |
238
+ | --copy-right | Right offset of the button | `0.5em` |
239
+ | --copy-size | Width and height of the button | `2em` |
240
+ | --copy-padding | Inner padding of the button | `0.5em` |
241
+ | --copy-background | Background color of the button | `inherit` |
242
+ | --copy-color | Foreground color of the button | `inherit` |
243
+ | --copy-border-radius | Border radius of the button | `4px` |
244
+ | --copy-border | Border of the button | `none` |
245
+ | --copy-z-index | Stacking order of the button | `2` |
246
+
247
+ ### Language tag variables
248
+
249
+ These apply when `langtag` is set to `true`.
250
+
251
+ | Variable | Description | Default value |
252
+ | :---------------------- | :------------------------------ | :------------ |
253
+ | --langtag-top | Top position of the langtag | `0` |
254
+ | --langtag-right | Right position of the langtag | `0` |
255
+ | --langtag-background | Background color of the langtag | `inherit` |
256
+ | --langtag-color | Text color of the langtag | `inherit` |
257
+ | --langtag-border-radius | Border radius of the langtag | `0` |
258
+ | --langtag-padding | Padding of the langtag | `1em` |
259
+
260
+ ### `CodeWindow` variables
261
+
262
+ | Variable | Description | Default value |
263
+ | :-------------------- | :--------------------------------------- | :---------------------------------- |
264
+ | --window-background | Background color of the window body | `#1e1e1e` |
265
+ | --window-border | Border of the window | `1px solid rgba(255, 255, 255, 0.1)`|
266
+ | --window-radius | Corner radius of the window | `0` |
267
+ | --titlebar-gap | Gap between items in the title bar | `0.5em` |
268
+ | --titlebar-padding | Padding of the title bar | `0.65em 1em` |
269
+ | --titlebar-background | Background color of the title bar | `#2d2d2d` |
270
+ | --titlebar-border | Bottom border of the title bar | `1px solid rgba(255, 255, 255, 0.1)`|
271
+ | --titlebar-color | Text color of the title bar | `rgba(255, 255, 255, 0.6)` |
272
+ | --titlebar-font-family| Font family of the title bar | `system-ui, -apple-system, sans-serif`|
273
+ | --titlebar-font-size | Font size of the title bar | `0.8125em` |
274
+ | --dot-gap | Gap between the macOS traffic-light dots | `0.5em` |
275
+ | --dot-size | Diameter of the macOS traffic-light dots | `0.75em` |
276
+ | --dot-close | Color of the "close" traffic-light dot | `#ff5f56` |
277
+ | --dot-minimize | Color of the "minimize" traffic-light dot| `#ffbd2e` |
278
+ | --dot-maximize | Color of the "maximize" traffic-light dot| `#27c93f` |
279
+ | --prompt-font-family | Font family of the terminal prompt | `ui-monospace, monospace` |
280
+ | --prompt-font-weight | Font weight of the terminal prompt | `700` |
281
+ | --prompt-color | Color of the terminal prompt | `inherit` |
282
+
126
283
  ## Svelte Syntax Highlighting
127
284
 
128
285
  Use the `HighlightSvelte` component for Svelte syntax highlighting.
@@ -241,6 +398,24 @@ The line number starts at `1`. Customize this via the `startingLineNumber` prop.
241
398
 
242
399
  Specify the lines to highlight using the `highlightedLines` prop. Indices start at zero.
243
400
 
401
+ ```svelte
402
+ <Highlight language={typescript} {code} let:highlighted>
403
+ <LineNumbers {highlighted} highlightedLines={[0, 2, 3, 14]} />
404
+ </Highlight>
405
+ ```
406
+
407
+ Use `--unhighlighted-opacity` or `--unhighlighted-filter` to de-emphasize the remaining lines and focus attention on the highlighted ones. Both only take effect when `highlightedLines` is non-empty.
408
+
409
+ ```svelte
410
+ <Highlight language={typescript} {code} let:highlighted>
411
+ <LineNumbers
412
+ {highlighted}
413
+ highlightedLines={[0, 2, 3, 14]}
414
+ --unhighlighted-opacity="0.4"
415
+ />
416
+ </Highlight>
417
+ ```
418
+
244
419
  Use `--highlighted-background` to customize the background color of highlighted lines.
245
420
 
246
421
  ```svelte
@@ -257,13 +432,18 @@ Use `--highlighted-background` to customize the background color of highlighted
257
432
 
258
433
  Use `--style-props` to customize styles.
259
434
 
260
- | Style prop | Description | Default value |
261
- | :----------------------- | :----------------------------------------- | :------------------------ |
262
- | --line-number-color | Text color of the line numbers | `currentColor` |
263
- | --border-color | Border color of the column of line numbers | `currentColor` |
264
- | --padding-left | Left padding for `td` elements | `1em` |
265
- | --padding-right | Right padding for `td` elements | `1em` |
266
- | --highlighted-background | Background color of highlighted lines | `rgba(254, 241, 96, 0.2)` |
435
+ | Style prop | Description | Default value |
436
+ | :----------------------- | :------------------------------------------------------ | :------------------------ |
437
+ | --line-number-color | Text color of the line numbers | `currentColor` |
438
+ | --border-color | Border color of the column of line numbers | `currentColor` |
439
+ | --padding | Fallback padding for `--padding-left` / `--padding-right` | `1em` |
440
+ | --padding-left | Left padding for `td` elements | `var(--padding, 1em)` |
441
+ | --padding-right | Right padding for `td` elements | `var(--padding, 1em)` |
442
+ | --highlighted-background | Background color of highlighted lines | `rgba(254, 241, 96, 0.2)` |
443
+ | --unhighlighted-opacity | Opacity of un-highlighted lines (focus mode) | `1` |
444
+ | --unhighlighted-filter | CSS filter for un-highlighted lines (focus mode) | `none` |
445
+
446
+ See [Styling with CSS variables](#styling-with-css-variables) for the full list, including container-level variables like `--border-radius`, `--width`, and `--overflow-x`.
267
447
 
268
448
  ```svelte
269
449
  <Highlight language={typescript} {code} let:highlighted>
@@ -274,6 +454,8 @@ Use `--style-props` to customize styles.
274
454
  --padding-left={0}
275
455
  --padding-right="3em"
276
456
  --highlighted-background="#000"
457
+ --border-radius="8px"
458
+ --max-width="40rem"
277
459
  />
278
460
  </Highlight>
279
461
  ```
@@ -303,6 +485,185 @@ With `HighlightAuto`:
303
485
  </HighlightAuto>
304
486
  ```
305
487
 
488
+ ## Copy Button
489
+
490
+ Compose the `CopyButton` component alongside `Highlight` to add a copy-to-clipboard button. Wrap both in a relatively-positioned container so the button can be positioned over the code block.
491
+
492
+ By default, it copies the `code` using the native [Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard/writeText) and shows a transient "copied" state. The button renders a copy icon that swaps to a checkmark on success; the `text` / `copiedText` props set the `aria-label` for each state. Clicks are ignored while in the "copied" state, so no duplicate copy fires.
493
+
494
+ ```svelte
495
+ <script>
496
+ import { Highlight, CopyButton } from "svelte-highlight";
497
+ import typescript from "svelte-highlight/languages/typescript";
498
+ import atomOneDark from "svelte-highlight/styles/atom-one-dark";
499
+
500
+ const code = "const add = (a: number, b: number) => a + b";
501
+ </script>
502
+
503
+ <svelte:head>
504
+ {@html atomOneDark}
505
+ </svelte:head>
506
+
507
+ <div style="position: relative">
508
+ <Highlight language={typescript} {code} />
509
+ <CopyButton {code} />
510
+ </div>
511
+ ```
512
+
513
+ ### Custom Copy Behavior
514
+
515
+ Pass a `copy` function to override the default copy behavior. It receives the `code` to copy and may be async (return a promise); the "copied" state is shown only once it resolves. Clicks are ignored while a copy is in flight, so a slow async `copy` can't fire duplicates.
516
+
517
+ ```svelte
518
+ <script>
519
+ function copy(code) {
520
+ navigator.clipboard.writeText(code);
521
+ console.log("Copied:", code);
522
+ }
523
+ </script>
524
+
525
+ <CopyButton {code} {copy} />
526
+ ```
527
+
528
+ The component dispatches a `copy` event on success and an `error` event if the copy behavior throws.
529
+
530
+ ```svelte
531
+ <CopyButton
532
+ {code}
533
+ on:copy={(e) => console.log(e.detail.code)}
534
+ on:error={(e) => console.error(e.detail.error)}
535
+ />
536
+ ```
537
+
538
+ ### Custom Button Content
539
+
540
+ 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.
541
+
542
+ ```svelte
543
+ <CopyButton {code} let:copied let:copying>
544
+ {#if copying}Copying…{:else if copied}Copied!{:else}Copy{/if}
545
+ </CopyButton>
546
+ ```
547
+
548
+ ### Custom Styles
549
+
550
+ Use `--copy-*` style props to customize the button.
551
+
552
+ ```svelte
553
+ <CopyButton
554
+ {code}
555
+ --copy-background="rgba(255, 255, 255, 0.1)"
556
+ --copy-color="#fff"
557
+ --copy-border-radius="8px"
558
+ />
559
+ ```
560
+
561
+ ### With Line Numbers
562
+
563
+ Compose `CopyButton` with `LineNumbers` by wrapping both in a relatively-positioned container.
564
+
565
+ ```svelte
566
+ <div style="position: relative">
567
+ <Highlight language={typescript} {code} let:highlighted>
568
+ <LineNumbers {highlighted} />
569
+ </Highlight>
570
+ <CopyButton {code} />
571
+ </div>
572
+ ```
573
+
574
+ ### With Language Tag
575
+
576
+ When using a language tag alongside `CopyButton`, offset `--langtag-top` and `--langtag-right` so the tag sits to the left of the button (the copy button defaults to `--copy-top: 0.5em`, `--copy-right: 0.5em`, and `--copy-size: 2em`).
577
+
578
+ ```svelte
579
+ <div style="position: relative">
580
+ <Highlight
581
+ language={typescript}
582
+ {code}
583
+ langtag
584
+ --langtag-top="0"
585
+ --langtag-right="3em"
586
+ --langtag-padding="0.25em 0.5em"
587
+ --langtag-font-size="0.75em"
588
+ />
589
+ <CopyButton {code} />
590
+ </div>
591
+ ```
592
+
593
+ ## Editable
594
+
595
+ `HighlightEditable` is a `contenteditable` code block. It re-highlights on every edit and keeps the caret where you left it.
596
+
597
+ Use `bind:code` to keep your state in sync.
598
+
599
+ ```svelte
600
+ <script>
601
+ import { HighlightEditable } from "svelte-highlight";
602
+ import typescript from "svelte-highlight/languages/typescript";
603
+ import atomOneDark from "svelte-highlight/styles/atom-one-dark";
604
+
605
+ let code = "const add = (a: number, b: number) => a + b";
606
+ </script>
607
+
608
+ <svelte:head>
609
+ {@html atomOneDark}
610
+ </svelte:head>
611
+
612
+ <HighlightEditable language={typescript} bind:code />
613
+ ```
614
+
615
+ ### Keyboard Behavior
616
+
617
+ - **Enter** inserts a newline.
618
+ - **Tab** / **Shift+Tab** indent or dedent the selected lines (or insert one indent at the caret). Set the indent size with the `tabSize` prop (default `2`).
619
+ - **Cmd/Ctrl+Z** undo and **Shift+Cmd/Ctrl+Z** (or **Ctrl+Y**) redo. Typing bursts collapse into a single undo step; cap the retained history with the `historyLimit` prop (default `200`).
620
+
621
+ ### Dispatched Events
622
+
623
+ `HighlightEditable` dispatches `change` (on every edit), `blur`, and `history` (whenever the undo/redo stack changes).
624
+
625
+ ```svelte
626
+ <HighlightEditable
627
+ language={typescript}
628
+ bind:code
629
+ on:change={(e) => console.log(e.detail.code)}
630
+ on:blur={(e) => console.log(e.detail.code)}
631
+ on:history={(e) => console.log(e.detail.canUndo, e.detail.canRedo)}
632
+ />
633
+ ```
634
+
635
+ ### Imperative API
636
+
637
+ Use `bind:this` to call methods on the instance.
638
+
639
+ ```svelte
640
+ <script>
641
+ let editor;
642
+ </script>
643
+
644
+ <HighlightEditable bind:this={editor} language={typescript} bind:code />
645
+
646
+ <button on:click={() => editor.undo()}>Undo</button>
647
+ <button on:click={() => editor.redo()}>Redo</button>
648
+ <button on:click={() => editor.indent()}>Indent</button>
649
+ <button on:click={() => editor.clear()}>Clear</button>
650
+ ```
651
+
652
+ Available methods: `undo`, `redo`, `focus`, `selectAll`, `insert`, `indent`, `outdent`, `setCode`, `clear`, `getCode`, `canUndo`, and `canRedo`.
653
+
654
+ ### Custom Styles
655
+
656
+ Customize the focus outline with the `--outline-color`, `--outline-width`, and `--outline-offset` style props.
657
+
658
+ ```svelte
659
+ <HighlightEditable
660
+ language={typescript}
661
+ bind:code
662
+ --outline-color="#42be65"
663
+ --outline-width="2px"
664
+ />
665
+ ```
666
+
306
667
  ## Language Targeting
307
668
 
308
669
  All `Highlight` components apply a `data-language` attribute on the codeblock containing the language name.
@@ -455,6 +816,344 @@ In the example below, the `HighlightAuto` component and injected styles are dyna
455
816
  />
456
817
  ```
457
818
 
819
+ ### Loading a language by name
820
+
821
+ The example above imports a specific language as a static string, which lets the bundler split out only the grammars you reference. When the language is known only at **runtime** — a Markdown fence (` ```ts `), an API field, or a user-selected value — use the `loadLanguage` helper to import a grammar by name:
822
+
823
+ ```svelte
824
+ <script>
825
+ import { Highlight, loadLanguage } from "svelte-highlight";
826
+ import github from "svelte-highlight/styles/github";
827
+
828
+ // The language name is not known until runtime.
829
+ export let language = "typescript";
830
+ export let code = "const add = (a, b) => a + b;";
831
+ </script>
832
+
833
+ <svelte:head>
834
+ {@html github}
835
+ </svelte:head>
836
+
837
+ {#await loadLanguage(language) then grammar}
838
+ <Highlight {code} language={grammar} />
839
+ {:catch}
840
+ <pre>{code}</pre>
841
+ {/await}
842
+ ```
843
+
844
+ `loadLanguage` accepts a [supported language name](SUPPORTED_LANGUAGES.md), dynamically imports its grammar, and resolves with the language object. It rejects with an `Unknown language` error for an unrecognized name, so handle the `{:catch}` block (or `.catch`) when the name comes from untrusted input.
845
+
846
+ > **Note:** Because the imported name is dynamic, the bundler cannot prune unused grammars and will emit a chunk for every language. Prefer a static `import` when the language is known ahead of time, and reach for `loadLanguage` only when it is not.
847
+
848
+ A practical case is rendering Markdown, where each fenced block declares its own language:
849
+
850
+ ```js
851
+ import { loadLanguage } from "svelte-highlight";
852
+
853
+ // e.g. from a Markdown fence: ```ts → "typescript"
854
+ async function highlightFence(fenceLang, code) {
855
+ const grammar = await loadLanguage(fenceLang);
856
+ return { code, language: grammar };
857
+ }
858
+ ```
859
+
860
+ ## Action
861
+
862
+ Use the `highlight` action to highlight existing `<pre><code>` markup in place. This is useful for progressively enhancing server-rendered content (e.g. markdown) without swapping in a component.
863
+
864
+ The action accepts the same `language` prop as the components. When `code` is omitted, the element's existing `textContent` is highlighted. Updating `code` re-highlights the element.
865
+
866
+ ```svelte
867
+ <script>
868
+ import { highlight } from "svelte-highlight";
869
+ import typescript from "svelte-highlight/languages/typescript";
870
+ import github from "svelte-highlight/styles/github";
871
+
872
+ const code = "const add = (a: number, b: number) => a + b;";
873
+ </script>
874
+
875
+ <svelte:head>
876
+ {@html github}
877
+ </svelte:head>
878
+
879
+ <pre><code use:highlight={{ language: typescript, code }}></code></pre>
880
+ ```
881
+
882
+ Omit `code` to highlight the element's existing contents:
883
+
884
+ ```svelte
885
+ <pre><code use:highlight={{ language: typescript }}
886
+ >const add = (a, b) => a + b;</code
887
+ ></pre>
888
+ ```
889
+
890
+ ## Code Window
891
+
892
+ Wrap a code block in `CodeWindow` to frame it with window chrome. It's purely cosmetic; the default slot renders your content unchanged.
893
+
894
+ Use the `variant` prop to choose the chrome style: `"macos"` (default) renders traffic-light dots, `"terminal"` renders a prompt, and `"plain"` renders just the title bar. The optional `title` is shown in the title bar.
895
+
896
+ ```svelte
897
+ <script>
898
+ import Highlight, { CodeWindow } from "svelte-highlight";
899
+ import typescript from "svelte-highlight/languages/typescript";
900
+ import github from "svelte-highlight/styles/github";
901
+
902
+ const code = "const add = (a: number, b: number) => a + b;";
903
+ </script>
904
+
905
+ <svelte:head>
906
+ {@html github}
907
+ </svelte:head>
908
+
909
+ <CodeWindow variant="macos" title="example.ts">
910
+ <Highlight language={typescript} {code} />
911
+ </CodeWindow>
912
+ ```
913
+
914
+ ### Terminal output
915
+
916
+ Pair `variant="terminal"` with a shell language to frame command-line output:
917
+
918
+ ```svelte
919
+ <script>
920
+ import Highlight, { CodeWindow } from "svelte-highlight";
921
+ import bash from "svelte-highlight/languages/bash";
922
+ import nord from "svelte-highlight/styles/nord";
923
+
924
+ const code = `$ npm install svelte-highlight
925
+
926
+ added 1 package in 1.2s`;
927
+ </script>
928
+
929
+ <svelte:head>
930
+ {@html nord}
931
+ </svelte:head>
932
+
933
+ <CodeWindow variant="terminal" title="bash">
934
+ <Highlight language={bash} {code} />
935
+ </CodeWindow>
936
+ ```
937
+
938
+ ### Theming the chrome
939
+
940
+ Every part of the chrome is driven by CSS variables (see [`CodeWindow` variables](#codewindow-variables)). Pass them as style props to restyle the window without `:global` overrides. For example, give the default square window rounded corners with `--window-radius`:
941
+
942
+ ```svelte
943
+ <CodeWindow
944
+ variant="macos"
945
+ title="example.ts"
946
+ --window-radius="12px"
947
+ --window-background="#0d1117"
948
+ --window-border="1px solid #30363d"
949
+ --titlebar-background="#161b22"
950
+ --titlebar-color="#8b949e"
951
+ >
952
+ <Highlight language={typescript} {code} />
953
+ </CodeWindow>
954
+ ```
955
+
956
+ The macOS traffic-light dots are themable too. Recolor them, or mute them to a single neutral color:
957
+
958
+ ```svelte
959
+ <CodeWindow
960
+ variant="macos"
961
+ title="example.ts"
962
+ --dot-close="#888"
963
+ --dot-minimize="#888"
964
+ --dot-maximize="#888"
965
+ >
966
+ <Highlight language={typescript} {code} />
967
+ </CodeWindow>
968
+ ```
969
+
970
+ The `plain` variant drops the dots and prompt for a minimal titled bar:
971
+
972
+ ```svelte
973
+ <CodeWindow variant="plain" title="example.ts">
974
+ <Highlight language={typescript} {code} />
975
+ </CodeWindow>
976
+ ```
977
+
978
+ ### Composing with other components
979
+
980
+ `CodeWindow` only frames its slot, so it composes with the rest of the library. Add `LineNumbers` inside it:
981
+
982
+ ```svelte
983
+ <script>
984
+ import Highlight, { CodeWindow, LineNumbers } from "svelte-highlight";
985
+ import typescript from "svelte-highlight/languages/typescript";
986
+ import github from "svelte-highlight/styles/github";
987
+
988
+ const code = `const add = (a, b) => a + b;
989
+ const sub = (a, b) => a - b;`;
990
+ </script>
991
+
992
+ <svelte:head>
993
+ {@html github}
994
+ </svelte:head>
995
+
996
+ <CodeWindow variant="macos" title="math.ts">
997
+ <Highlight language={typescript} {code} let:highlighted>
998
+ <LineNumbers {highlighted} hideBorder />
999
+ </Highlight>
1000
+ </CodeWindow>
1001
+ ```
1002
+
1003
+ Or layer a `CopyButton` over it by wrapping both in a relatively-positioned container:
1004
+
1005
+ ```svelte
1006
+ <div style="position: relative">
1007
+ <CodeWindow variant="macos" title="example.ts">
1008
+ <Highlight language={typescript} {code} />
1009
+ </CodeWindow>
1010
+ <!-- Offset the button so it clears the title bar. -->
1011
+ <CopyButton {code} --copy-top="3em" />
1012
+ </div>
1013
+ ```
1014
+
1015
+ ## Animation
1016
+
1017
+ Use `Typewriter` inside `Highlight`'s default slot with the `highlighted` prop. It prints the code one character at a time, syntax highlighting included. A blinking caret marks the end of the typed text and hides when typing stops.
1018
+
1019
+ Unrevealed text stays in the layout but invisible, so the block is full height from the start. Content below won't jump as characters appear. You don't need a `min-height` hack.
1020
+
1021
+ ```svelte
1022
+ <script>
1023
+ import Highlight, { Typewriter } from "svelte-highlight";
1024
+ import typescript from "svelte-highlight/languages/typescript";
1025
+ import github from "svelte-highlight/styles/github";
1026
+
1027
+ const code = "const add = (a: number, b: number) => a + b;";
1028
+ </script>
1029
+
1030
+ <svelte:head>
1031
+ {@html github}
1032
+ </svelte:head>
1033
+
1034
+ <Highlight language={typescript} {code} let:highlighted>
1035
+ <Typewriter {highlighted} />
1036
+ </Highlight>
1037
+ ```
1038
+
1039
+ Set `speed` (milliseconds per character) and pause with `play`. Turn `play` back on to pick up where you left off. A new `highlighted` value starts over from the first character. Fire `on:done` when the last character is visible.
1040
+
1041
+ ```svelte
1042
+ <Highlight language={typescript} {code} let:highlighted>
1043
+ <Typewriter
1044
+ {highlighted}
1045
+ speed={50}
1046
+ {play}
1047
+ on:done={() => console.log("revealed")}
1048
+ />
1049
+ </Highlight>
1050
+ ```
1051
+
1052
+ 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`.
1053
+
1054
+ ## Terminal Output
1055
+
1056
+ 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.
1057
+
1058
+ ```svelte
1059
+ <script>
1060
+ import { AnsiOutput } from "svelte-highlight";
1061
+
1062
+ // Raw program output, escape codes included.
1063
+ const text = "\x1b[32m✓\x1b[0m build succeeded \x1b[2m(1.2s)\x1b[0m";
1064
+ </script>
1065
+
1066
+ <AnsiOutput {text} />
1067
+ ```
1068
+
1069
+ Malformed or unsupported escape sequences are dropped. Nothing throws.
1070
+
1071
+ ### Theming the palette
1072
+
1073
+ Pass `--ansi-*` style props to recolor the output. The 16 base colors, default foreground and background, and bold/dim weight and opacity all come from CSS variables with hex fallbacks:
1074
+
1075
+ ```svelte
1076
+ <AnsiOutput
1077
+ {text}
1078
+ --ansi-background="#0d1117"
1079
+ --ansi-red="#ff7b72"
1080
+ --ansi-green="#3fb950"
1081
+ />
1082
+ ```
1083
+
1084
+ 256-color and 24-bit truecolor codes resolve to RGB.
1085
+
1086
+ ### Readable colors
1087
+
1088
+ With `autoContrast` on (the default), spans that set a background get a readable foreground. If the chosen text color would disappear on that background (white on white, for example), it flips to black or white, whichever reads better. Only spans with a background are adjusted. Set `autoContrast={false}` to keep the ANSI colors as-is.
1089
+
1090
+ ```svelte
1091
+ <AnsiOutput {text} autoContrast={false} />
1092
+ ```
1093
+
1094
+ ### Pairing with `CodeWindow`
1095
+
1096
+ Put `AnsiOutput` inside `CodeWindow variant="terminal"` for the prompt and title bar:
1097
+
1098
+ ```svelte
1099
+ <script>
1100
+ import { AnsiOutput, CodeWindow } from "svelte-highlight";
1101
+
1102
+ const text = "\x1b[1;32m$\x1b[0m npm run build";
1103
+ </script>
1104
+
1105
+ <CodeWindow variant="terminal" title="bash">
1106
+ <AnsiOutput {text} />
1107
+ </CodeWindow>
1108
+ ```
1109
+
1110
+ Call `parseAnsi` directly if you need the segments yourself:
1111
+
1112
+ ```js
1113
+ import { parseAnsi } from "svelte-highlight";
1114
+
1115
+ parseAnsi("\x1b[31merror\x1b[0m");
1116
+ // => [{ text: "error", fg: { name: "red" } }]
1117
+ ```
1118
+
1119
+ ## File Tabs
1120
+
1121
+ `FileTabs` groups code snippets behind a tab strip, like files in an editor. Pass file names as `files`, then use `let:active` in the default slot to render the matching snippet.
1122
+
1123
+ Arrow keys move between tabs; `Home` and `End` jump to the first and last. The markup follows the WAI-ARIA tabs pattern (`role="tablist"`, `role="tab"`, `role="tabpanel"`).
1124
+
1125
+ ```svelte
1126
+ <script>
1127
+ import Highlight, { FileTabs } from "svelte-highlight";
1128
+ import javascript from "svelte-highlight/languages/javascript";
1129
+ import typescript from "svelte-highlight/languages/typescript";
1130
+ import github from "svelte-highlight/styles/github";
1131
+
1132
+ const sources = {
1133
+ "App.svelte": { language: typescript, code: "const answer = 42;" },
1134
+ "index.js": { language: javascript, code: "export default answer;" },
1135
+ };
1136
+
1137
+ const files = Object.keys(sources);
1138
+ </script>
1139
+
1140
+ <svelte:head>
1141
+ {@html github}
1142
+ </svelte:head>
1143
+
1144
+ <FileTabs {files} let:active>
1145
+ <Highlight language={sources[active].language} code={sources[active].code} />
1146
+ </FileTabs>
1147
+ ```
1148
+
1149
+ `bind:active` sets the open tab from your code. `on:change` fires when the user picks a different one.
1150
+
1151
+ ```svelte
1152
+ <FileTabs {files} bind:active on:change={(e) => console.log(e.detail.active)}>
1153
+ <Highlight language={sources[active].language} code={sources[active].code} />
1154
+ </FileTabs>
1155
+ ```
1156
+
458
1157
  ## Component API
459
1158
 
460
1159
  ### `Highlight`
@@ -503,6 +1202,55 @@ In the example below, the `HighlightAuto` component and injected styles are dyna
503
1202
 
504
1203
  `$$restProps` are forwarded to the top-level `div` element.
505
1204
 
1205
+ ### `CopyButton`
1206
+
1207
+ #### Props
1208
+
1209
+ | Name | Type | Default value |
1210
+ | :--------- | :----------------------------------------- | :------------------------------------------- |
1211
+ | code | `string` | N/A (required) |
1212
+ | copy | `(code: string) => void \| Promise<void>` | `(code) => navigator.clipboard.writeText(code)` |
1213
+ | timeout | `number` | `2000` |
1214
+ | text | `string` | `"Copy"` |
1215
+ | copiedText | `string` | `"Copied!"` |
1216
+
1217
+ `$$restProps` are forwarded to the top-level `button` element.
1218
+
1219
+ #### Dispatched Events
1220
+
1221
+ - **on:copy**: fired after a successful copy, with `{ code }`
1222
+ - **on:error**: fired if the copy behavior throws, with `{ error }`
1223
+
1224
+ ```svelte
1225
+ <CopyButton
1226
+ {code}
1227
+ on:copy={(e) => console.log(e.detail.code)}
1228
+ on:error={(e) => console.error(e.detail.error)}
1229
+ />
1230
+ ```
1231
+
1232
+ ### `CodeWindow`
1233
+
1234
+ #### Props
1235
+
1236
+ | Name | Type | Default value |
1237
+ | :------ | :--------------------------------- | :------------ |
1238
+ | variant | `"macos" \| "terminal" \| "plain"` | `"macos"` |
1239
+ | title | `string` | `""` |
1240
+
1241
+ `$$restProps` are forwarded to the top-level `div` element.
1242
+
1243
+ ### `AnsiOutput`
1244
+
1245
+ #### Props
1246
+
1247
+ | Name | Type | Default value |
1248
+ | :----------- | :-------- | :------------- |
1249
+ | text | `string` | N/A (required) |
1250
+ | autoContrast | `boolean` | `true` |
1251
+
1252
+ `$$restProps` are forwarded to the top-level `pre` element.
1253
+
506
1254
  ### `HighlightSvelte`
507
1255
 
508
1256
  #### Props
@@ -572,6 +1320,83 @@ import type { LanguageName } from "svelte-highlight";
572
1320
  />
573
1321
  ```
574
1322
 
1323
+ ### `HighlightEditable`
1324
+
1325
+ #### Props
1326
+
1327
+ | Name | Type | Default value |
1328
+ | :----------- | :--------------------------------------------- | :------------- |
1329
+ | code | `string` | `""` |
1330
+ | language | { name: `string`; register: hljs => `object` } | N/A (required) |
1331
+ | tabSize | `number` | `2` |
1332
+ | historyLimit | `number` | `200` |
1333
+
1334
+ `$$restProps` are forwarded to the top-level `pre` element.
1335
+
1336
+ `code` supports two-way binding (`bind:code`).
1337
+
1338
+ #### Methods
1339
+
1340
+ Use `bind:this`, then call `undo()`, `redo()`, `focus()`, `selectAll()`, `insert(text)`, `indent()`, `outdent()`, `setCode(value)`, `clear()`, `getCode()`, `canUndo()`, or `canRedo()`.
1341
+
1342
+ #### Dispatched Events
1343
+
1344
+ - **on:change**: fired on every edit, with `{ code }`
1345
+ - **on:blur**: fired when the editor loses focus, with `{ code }`
1346
+ - **on:history**: fired when the undo/redo stack changes, with `{ entries, index, canUndo, canRedo }`
1347
+
1348
+ ```svelte
1349
+ <HighlightEditable
1350
+ language={typescript}
1351
+ bind:code
1352
+ on:change={(e) => console.log(e.detail.code)}
1353
+ on:history={(e) => console.log(e.detail.canUndo, e.detail.canRedo)}
1354
+ />
1355
+ ```
1356
+
1357
+ ### `FileTabs`
1358
+
1359
+ #### Props
1360
+
1361
+ | Name | Type | Default value |
1362
+ | :----- | :--------- | :------------- |
1363
+ | files | `string[]` | N/A (required) |
1364
+ | active | `string` | `files[0]` |
1365
+
1366
+ `$$restProps` are forwarded to the top-level `div` element. `active` supports `bind:active`.
1367
+
1368
+ #### Dispatched Events
1369
+
1370
+ - **on:change**: fired when the user picks a tab, with `{ active }`
1371
+
1372
+ ```svelte
1373
+ <FileTabs {files} on:change={(e) => console.log(e.detail.active)} let:active>
1374
+ <Highlight language={sources[active].language} code={sources[active].code} />
1375
+ </FileTabs>
1376
+ ```
1377
+
1378
+ ### `Typewriter`
1379
+
1380
+ #### Props
1381
+
1382
+ | Name | Type | Default value |
1383
+ | :---------- | :-------- | :------------ |
1384
+ | highlighted | `string` | `""` |
1385
+ | speed | `number` | `30` |
1386
+ | play | `boolean` | `true` |
1387
+
1388
+ `$$restProps` are forwarded to the top-level `pre` element.
1389
+
1390
+ #### Dispatched Events
1391
+
1392
+ - **on:done**: fires when typing finishes, or immediately when reduced motion is on
1393
+
1394
+ ```svelte
1395
+ <Highlight language={typescript} {code} let:highlighted>
1396
+ <Typewriter {highlighted} on:done={() => console.log("revealed")} />
1397
+ </Highlight>
1398
+ ```
1399
+
575
1400
  ## [Supported Languages](SUPPORTED_LANGUAGES.md)
576
1401
 
577
1402
  ## [Supported Styles](SUPPORTED_STYLES.md)