svelte-streamdown 2.4.5 → 2.5.1

package/README.md

@@ -62,6 +62,7 @@ Full support for
 - Escaping currency symbols ($140)
 - Complex tables
 - Footnotes [^1]
+- Inline citations [ref] [ref2]
 
 [^1]:
     Reference render in a popover by default.
@@ -133,11 +134,11 @@ pie title Project Time Allocation
 
 | H1                        | H2  | H3  |
 | ------------------------- | --- | --- |
-| This cell spans 3 columns |     |     |
+| This cell spans 3 columns |||
 
 | Header 1                  | Header 2 | Header 3 |
 | ------------------------- | -------- | -------- |
-| This cell spans 2 columns |          | Normal   |
+| This cell spans 2 columns || Normal   |
 | Normal                    | Normal   | Normal   |
 
 #### Rowspan
@@ -153,7 +154,7 @@ pie title Project Time Allocation
 | --------------- | -------- |
 | Cell B          | Cell A   |
 | --------------- | -------- |
-| Footer          |          |
+| Footer          ||
 
 #### Column alignment
 
@@ -238,6 +239,98 @@ III. Third item
     :   Topic 3   :  Description 3
     :   Topic 3   :  Description 3
 
+### Citation Support
+
+Streamdown supports inline citations that allow you to reference external sources and display them in interactive popovers. Citations work out-of-the-box with a simple object structure and support nested references like this `[cloudflare.website, vercel]` will render into [cloudflare.website, vercel]
+
+To enable inline citations, pass a `sources` object as a prop to the `Streamdown` component.
+
+#### Basic Usage
+
+```svelte
+<script>
+  import { Streamdown } from 'svelte-streamdown';
+
+  let content = `According to [smith2023], AI is advancing rapidly. See also [nested.subsection] for related work.`;
+
+  let sources = {
+    "smith2023": {
+      title: "AI Research Paper",
+      url: "https://example.com/paper",
+      content: "Detailed content of the citation..."
+    },
+    "nested": {
+      "subsection": {
+        title: "Nested Citation",
+        url: "https://example.com/nested"
+      }
+    }
+  };
+</script>
+
+<Streamdown {content} {sources} />
+```
+
+#### Default Citation Structure
+
+Citations work with objects containing these properties:
+
+- `title (or name or author)`: Display title for the citation
+- `url (or href, url, link or source)`: Link to the source
+- `content (or text, summary or excerpt)`: Rich content to display in carousel mode
+
+
+#### Display Modes
+
+Streamdown offers two ways to display citations:
+
+- **List View**: Shows all citations in a compact list format
+- **Carousel View** (default): Step-through navigation for multiple citations with full content display
+
+You can control the display mode using the `inlineCitationsMode` prop:
+
+```svelte
+<!-- List view -->
+<Streamdown {content} {sources} inlineCitationsMode="list" />
+
+<!-- Carousel view (default) -->
+<Streamdown {content} {sources} inlineCitationsMode="carousel" />
+```
+
+#### Citation Popovers
+
+Citations appear as clickable buttons that open popovers when clicked. The popover shows:
+- Source title and URL (when available)
+- Favicon from the source domain
+- Rich content (in carousel mode)
+- Navigation controls (in carousel mode for multiple citations)
+
+#### Custom Citation Rendering
+
+If your citation data structure doesn't match the default format, you can customize how citations are rendered using `inlineCitationPreview`, `inlineCitationContent` or `inlineCitationPopover` snippets:
+
+```svelte
+<Streamdown {content} {sources}>
+  {#snippet inlineCitationPreview({ token })}
+    <!-- Customize the clickable citation button -->   
+      {token.keys[0]}
+  {/snippet}
+
+  {#snippet inlineCitationContent({ source, key, token })}
+    <!-- Customize content displayed in popover -->
+    <div class="custom-content">
+      <h4>{source.customTitle || key}</h4>
+      <p>{source.customDescription}</p>
+    </div>
+  {/snippet}
+</Streamdown>
+```
+
+These snippets allow you to:
+- **`inlineCitationPreview`**: Customize the content of the clickable button that appears in the text
+- **`inlineCitationContent`**: Customize how individual citation content is displayed within popovers
+- **`inlineCitationPopover`**: Completely customize the list of citations
+
 ## 🔄 Differences from Original React Version
 
 This Svelte port maintains feature parity with the original [Streamdown](https://streamdown.ai/) while adapting to Svelte's patterns:
@@ -369,6 +462,7 @@ This heading will use a custom component!`;
 | Prop                       | Type                                                                             | Default          | Description                                                                                                                                        |
 | -------------------------- | -------------------------------------------------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `content`                  | `string`                                                                         | -                | **Required.** The markdown content to render                                                                                                       |
+| `sources`                  | `Record<string, any>`                                                            | -                | Citation data object for inline citations                                                                                                          |
 | `class`                    | `string`                                                                         | -                | CSS class names for the wrapper element                                                                                                            |
 | `parseIncompleteMarkdown`  | `boolean`                                                                        | `true`           | Parse and fix incomplete markdown syntax                                                                                                           |
 | `defaultOrigin`            | `string`                                                                         | -                | Default origin for relative URLs                                                                                                                   |
@@ -405,7 +499,7 @@ This heading will use a custom component!`;
 
 **Tables**: `table`, `thead`, `tbody`, `tr`, `th`, `td`, `tfoot`
 
-**Special Content**: `blockquote`, `hr`, `alert`, `mermaid`, `math`, `footnoteRef`
+**Special Content**: `blockquote`, `hr`, `alert`, `mermaid`, `math`, `footnoteRef`, `inlineCitation`
 
 **Note**: The above elements are **supported by Streamdown** and should be customized using individual props or the theme system.
 

package/dist/Block.svelte

@@ -4,17 +4,17 @@
 	import { lex, type StreamdownToken } from './marked/index.js';
 	import AnimatedText from './AnimatedText.svelte';
 	import { useStreamdown } from './context.svelte.js';
+	import { getContext } from 'svelte';
 
 	let {
-		block,
-		insideFootnote = false
+		block
 	}: {
 		block: string;
-		insideFootnote?: boolean;
 	} = $props();
 
 	const streamdown = useStreamdown();
 	const tokens = $derived(lex(parseIncompleteMarkdown(block.trim()), streamdown.extensions));
+	const insidePopover = getContext('POPOVER');
 </script>
 
 {#snippet renderChildren(tokens: StreamdownToken[])}
@@ -24,7 +24,7 @@
 			{@const isTextOnlyNode = children.length === 0}
 			<Element {token}>
 				{#if isTextOnlyNode}
-					{#if streamdown.animation.enabled && !insideFootnote}
+					{#if streamdown.animation.enabled && !insidePopover}
 						<AnimatedText text={'text' in token ? token.text : ''} />
 					{:else}
 						{'text' in token ? token.text : ''}

package/dist/Block.svelte.d.ts

@@ -1,6 +1,5 @@
 type $$ComponentProps = {
     block: string;
-    insideFootnote?: boolean;
 };
 declare const Block: import("svelte").Component<$$ComponentProps, {}, "">;
 type Block = ReturnType<typeof Block>;

package/dist/Elements/Alert.svelte

@@ -22,8 +22,10 @@
 
 	const {
 		children,
-		token
+		token,
+		id
 	}: {
+		id: string;
 		children: Snippet;
 		token: AlertToken;
 	} = $props();
@@ -37,6 +39,7 @@
 	render={streamdown.snippets.alert}
 >
 	<div
+		data-streamdown-alert={id}
 		style={streamdown.isMounted ? streamdown.animationBlockStyle : ''}
 		class={`${streamdown.theme.alert.base} ${streamdown.theme.alert[token.variant]}`}
 	>

package/dist/Elements/Alert.svelte.d.ts

@@ -1,6 +1,7 @@
 import type { AlertToken } from '../marked/index.js';
 import type { Snippet } from 'svelte';
 type $$ComponentProps = {
+    id: string;
     children: Snippet;
     token: AlertToken;
 };

package/dist/Elements/Citation.svelte

@@ -0,0 +1,260 @@
+<script lang="ts">
+	import { useStreamdown } from '../context.svelte.js';
+	import Slot from './Slot.svelte';
+	import { useClickOutside } from '../utils/useClickOutside.svelte.js';
+	import { scale } from 'svelte/transition';
+	import Block from '../Block.svelte';
+	import { useKeyDown } from '../utils/useKeyDown.svelte.js';
+	import type { CitationToken } from '../marked/marked-citations.js';
+	import { StepperState } from './stepperState.svelte.js';
+	import { Popover } from './popover.svelte.js';
+	import { get } from '../utils/get.js';
+	import { chevronLeft, chevronRight } from './icons.js';
+
+	const {
+		token
+	}: {
+		token: CitationToken;
+	} = $props();
+	const streamdown = useStreamdown();
+	const id = $props.id();
+	const popover = new Popover();
+
+	const citationWithSources = $derived.by(() => {
+		return token.keys.reduce((acc, key) => {
+			const source = get<Record<string, any>>(streamdown.sources, key);
+			const safeUrl = (url: string | null) => {
+				if (url == null) return null;
+				try {
+					return new URL(url);
+				} catch (error) {
+					return null;
+				}
+			};
+			if (source) {
+				const url = safeUrl(source.url ?? source.href ?? source.link ?? source.source);
+				acc.push({
+					key,
+					title: source.title ?? source.name ?? source.author ?? null,
+					url,
+					host: url ? url.host.replace('www.', '') : null,
+					favicon: url ? `https://www.google.com/s2/favicons?domain=${url.hostname}&sz=128` : null,
+					content: source.content ?? source.text ?? source.summary ?? source.excerpt ?? null,
+					source
+				});
+			}
+			return acc;
+		}, [] as CitationWithSource[]);
+	});
+	useKeyDown({
+		keys: ['Escape'],
+		get isActive() {
+			return popover.isOpen;
+		},
+		callback: () => {
+			popover.isOpen = false;
+		}
+	});
+	const clickOutside = useClickOutside({
+		get isActive() {
+			return popover.isOpen;
+		},
+		callback: () => {
+			popover.isOpen = false;
+		}
+	});
+
+	const stepper = new StepperState({
+		get items() {
+			return citationWithSources;
+		},
+		keyFramesOptions: { duration: 200, easing: 'ease-in-out', fill: 'forwards' }
+	});
+
+	type CitationWithSource = Record<string, any> & {
+		key: string;
+		title: string | null;
+		url: URL | null;
+		favicon: string | null;
+		content: string | null;
+		source: Record<string, any>;
+	};
+</script>
+
+{#if popover.isOpen}
+	<dialog
+		data-streamdown-citation-popover={id}
+		id={'citation-popover-' + id}
+		aria-modal="false"
+		transition:scale|global={{ start: 0.95, duration: 200 }}
+		{@attach clickOutside.attachment}
+		{@attach popover.popoverAttachment}
+		open
+		class={`${streamdown.theme.components.popover}`}
+		style:max-width="400px"
+	>
+		<Slot
+			props={{
+				token,
+				isOpen: popover.isOpen
+			}}
+			render={streamdown.snippets.inlineCitationPopover}
+		>
+			{#if streamdown.inlineCitationsMode === 'carousel'}
+				{@render carouselView()}
+			{:else}
+				{@render listView()}
+			{/if}
+		</Slot>
+	</dialog>
+{/if}
+
+{#snippet listView()}
+	<div class={streamdown.theme.inlineCitation.list.base}>
+		{#each citationWithSources as { favicon, key, source, title, url }}
+			<Slot render={streamdown.snippets.inlineCitationContent} props={{ source, key, token }}>
+				<a
+					class={streamdown.theme.inlineCitation.list.item}
+					href={url?.toString()}
+					target="_blank"
+					rel="noopener noreferrer"
+				>
+					{#if title}
+						<span class={streamdown.theme.inlineCitation.list.title}>{title}</span>
+					{/if}
+					{#if url}
+						<span class={streamdown.theme.inlineCitation.list.url}>
+							{#if favicon}
+								<img
+									src={favicon}
+									alt={title || url.host}
+									class={streamdown.theme.inlineCitation.list.favicon}
+								/>
+							{/if}
+							{url.host}{url.pathname === '/' ? '' : url.pathname}
+						</span>
+					{/if}
+				</a>
+			</Slot>
+		{/each}
+	</div>
+{/snippet}
+
+{#snippet carouselView()}
+	{#if citationWithSources.length > 1}
+		<div class={streamdown.theme.inlineCitation.carousel.header}>
+			<div class={streamdown.theme.inlineCitation.carousel.stepCounter}>
+				{stepper.activeStep + 1}
+				/ {citationWithSources.length}
+			</div>
+			<div class={streamdown.theme.inlineCitation.carousel.buttons}>
+				<button
+					disabled={!stepper.canGoPrevious}
+					class={streamdown.theme.components.button}
+					onclick={() => stepper.previous()}
+				>
+					{@render (streamdown.icons?.chevronLeft || chevronLeft)()}
+				</button>
+				<button
+					disabled={!stepper.canGoNext}
+					class={streamdown.theme.components.button}
+					onclick={() => stepper.next()}
+				>
+					{@render (streamdown.icons?.chevronRight || chevronRight)()}
+				</button>
+			</div>
+		</div>
+	{/if}
+	<div
+		use:stepper.scroller
+		style:height={Number.isFinite(stepper.stepHeights[stepper.activeStep])
+			? `${stepper.stepHeights[stepper.activeStep]}px`
+			: 'auto'}
+		style:overflow="hidden"
+		style:position="relative"
+		style:transition-duration="200ms"
+		style:transition-timing-function="ease-in-out"
+		aria-label="Citations-${id}"
+	>
+		<div
+			bind:this={stepper.stepContainer}
+			style:display="grid"
+			style:transition-duration={`${200}ms`}
+			style:width="100%"
+			style:grid-template-columns="repeat({citationWithSources.length}, 100%)"
+		>
+			{#each citationWithSources as { favicon, key, source, title, url, content }, index}
+				<div
+					bind:offsetHeight={stepper.stepHeights[index]}
+					data-step={index}
+					tabindex={stepper.activeStep === index ? 0 : -1}
+					inert={stepper.activeStep !== index}
+					role="tabpanel"
+					style:height="fit-content"
+					style:width="100%"
+					style:flex-grow="1"
+					aria-label="Citation-${id}"
+				>
+					<Slot render={streamdown.snippets.inlineCitationContent} props={{ source, key, token }}>
+						{#if url || title}
+							<div class="mb-4">
+								{#if title}
+									<div class={streamdown.theme.inlineCitation.carousel.title}>
+										{title}
+									</div>
+								{/if}
+								{#if url}
+									<a
+										href={url.toString()}
+										target="_blank"
+										rel="noopener noreferrer"
+										class={streamdown.theme.inlineCitation.carousel.url}
+									>
+										{#if favicon}
+											<img
+												src={favicon}
+												alt={title || url.host}
+												class={streamdown.theme.inlineCitation.carousel.favicon}
+											/>
+										{/if}
+										<!-- Skip search params -->
+										{url.host}{url.pathname === '/' ? '' : url.pathname}
+									</a>
+								{/if}
+							</div>
+						{/if}
+						{#if content}
+							<Block block={content} />
+						{/if}
+					</Slot>
+				</div>
+			{/each}
+		</div>
+	</div>
+{/snippet}
+
+{#if citationWithSources.length > 0}
+	<button
+		data-streamdown-citation-preview={id}
+		style={streamdown.animationBlockStyle}
+		bind:this={popover.reference}
+		class={streamdown.theme.inlineCitation.preview}
+		onclick={() => (popover.isOpen = !popover.isOpen)}
+		aria-expanded={popover.isOpen}
+		aria-haspopup="dialog"
+		aria-controls={'citation-popover-' + id}
+		{@attach clickOutside.attachment}
+	>
+		<Slot
+			render={streamdown.snippets.inlineCitationPreview}
+			props={{
+				token
+			}}
+		>
+			{citationWithSources[0]?.url?.host ??
+				citationWithSources[0]?.title ??
+				citationWithSources[0]?.key}
+			{citationWithSources.length > 1 ? ` +${citationWithSources.length - 1}` : ''}
+		</Slot>
+	</button>
+{/if}

package/dist/Elements/Citation.svelte.d.ts

@@ -0,0 +1,7 @@
+import type { CitationToken } from '../marked/marked-citations.js';
+type $$ComponentProps = {
+    token: CitationToken;
+};
+declare const Citation: import("svelte").Component<$$ComponentProps, {}, "">;
+type Citation = ReturnType<typeof Citation>;
+export default Citation;

package/dist/Elements/Code.svelte

@@ -6,11 +6,14 @@
 	import type { Tokens } from 'marked';
 	import { type ThemedToken } from 'shiki';
 	import { untrack } from 'svelte';
+	import { checkIcon, copyIcon, downloadIcon } from './icons.js';
 
 	const {
-		token
+		token,
+		id
 	}: {
 		token: Tokens.Code;
+		id: string;
 	} = $props();
 
 	const streamdown = useStreamdown();
@@ -48,6 +51,7 @@
 </script>
 
 <div
+	data-streamdown-code={id}
 	style={streamdown.isMounted ? streamdown.animationBlockStyle : ''}
 	class={streamdown.theme.code.base}
 >
@@ -56,16 +60,20 @@
 		{#if streamdown.controls.code}
 			<div class={streamdown.theme.code.buttons}>
 				<button
-					class={streamdown.theme.code.button}
+					class={streamdown.theme.components.button}
 					onclick={downloadCode}
-					title="Download file"
+					title="Download code"
 					type="button"
 				>
 					{@render (streamdown.icons?.download || downloadIcon)()}
 				</button>
 
-				<button class={streamdown.theme.code.button} onclick={copy.copy} type="button">
-					{@render (streamdown.icons?.copy || copyIcon)()}
+				<button class={streamdown.theme.components.button} onclick={copy.copy} type="button">
+					{#if copy.isCopied}
+						{@render (streamdown.icons?.check || checkIcon)()}
+					{:else}
+						{@render (streamdown.icons?.copy || copyIcon)()}
+					{/if}
 				</button>
 			</div>
 		{/if}
@@ -107,39 +115,3 @@
 		</span>
 	{/each}
 {/snippet}
-
-{#snippet copyIcon()}
-	<svg
-		xmlns="http://www.w3.org/2000/svg"
-		width="100%"
-		height="100%"
-		viewBox="0 0 24 24"
-		fill="none"
-		stroke="currentColor"
-		stroke-width="2"
-		stroke-linecap="round"
-		stroke-linejoin="round"
-		class="lucide lucide-clipboard-icon lucide-clipboard"
-		><rect width="8" height="4" x="8" y="2" rx="1" ry="1" /><path
-			d="M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2"
-		/></svg
-	>
-{/snippet}
-
-{#snippet downloadIcon()}
-	<svg
-		xmlns="http://www.w3.org/2000/svg"
-		width="100%"
-		height="100%"
-		viewBox="0 0 24 24"
-		fill="none"
-		stroke="currentColor"
-		stroke-width="2"
-		stroke-linecap="round"
-		stroke-linejoin="round"
-		class="lucide lucide-download-icon lucide-download"
-		><path d="M12 15V3" /><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" /><path
-			d="m7 10 5 5 5-5"
-		/></svg
-	>
-{/snippet}

package/dist/Elements/Code.svelte.d.ts

@@ -1,6 +1,7 @@
 import type { Tokens } from 'marked';
 type $$ComponentProps = {
     token: Tokens.Code;
+    id: string;
 };
 declare const Code: import("svelte").Component<$$ComponentProps, {}, "">;
 type Code = ReturnType<typeof Code>;