svelte-streamdown 2.4.5 → 2.5.0

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/Citation.svelte

@@ -0,0 +1,285 @@
+<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';
+
+	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
+		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}
+
+{#snippet chevronRight()}
+	<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"><path d="m9 18 6-6-6-6" /></svg
+	>
+{/snippet}
+
+{#snippet chevronLeft()}
+	<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"><path d="m15 18-6-6 6-6" /></svg
+	>
+{/snippet}
+
+{#if citationWithSources.length > 0}
+	<button
+		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

@@ -56,7 +56,7 @@
 		{#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"
 					type="button"
@@ -64,7 +64,7 @@
 					{@render (streamdown.icons?.download || downloadIcon)()}
 				</button>
 
-				<button class={streamdown.theme.code.button} onclick={copy.copy} type="button">
+				<button class={streamdown.theme.components.button} onclick={copy.copy} type="button">
 					{@render (streamdown.icons?.copy || copyIcon)()}
 				</button>
 			</div>
@@ -119,7 +119,6 @@
 		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
@@ -137,7 +136,6 @@
 		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

package/dist/Elements/Element.svelte

@@ -10,6 +10,7 @@
 	import Slot from './Slot.svelte';
 	import { useStreamdown } from '../context.svelte.js';
 	import FootnoteRef from './FootnoteRef.svelte';
+	import Citation from './Citation.svelte';
 	let { token, children }: { token: StreamdownToken; children: Snippet } = $props();
 	const streamdown = useStreamdown();
 
@@ -112,7 +113,7 @@
 	</Slot>
 {:else if token.type === 'table'}
 	<Slot props={{ token, children }} render={streamdown.snippets.table}>
-		<div {style} class={streamdown.theme.table.base}>
+		<div {style} class={streamdown.theme.table.base} style:overscroll-behavior-x="none">
 			<table class={streamdown.theme.table.table}>
 				{@render children()}
 			</table>
@@ -227,7 +228,13 @@
 {:else if token.type === 'alert'}
 	<Alert {token} {children} />
 {:else if token.type === 'footnoteRef'}
-	<FootnoteRef {token} />
+	<Slot props={{ token }} render={streamdown.snippets.footnoteRef}>
+		<FootnoteRef {token} />
+	</Slot>
+{:else if token.type === 'inline-citations'}
+	<Slot props={{ token }} render={streamdown.snippets.inlineCitation}>
+		<Citation {token} />
+	</Slot>
 {:else if token.type === 'footnote'}
 	<!-- TODO Footnotes are rendered inside the FootnoteRef popover -->
 {:else if token.type === 'descriptionList'}