svelte-streamdown 0.0.1 → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Arnaud Derbey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,58 +1,536 @@
-# Svelte library
+# Svelte Streamdown
 
-Everything you need to build a Svelte library, powered by [`sv`](https://npmjs.com/package/sv).
+[![npm version](https://badge.fury.io/js/svelte-streamdown.svg)](https://badge.fury.io/js/svelte-streamdown)
 
-Read more about creating a library [in the docs](https://svelte.dev/docs/kit/packaging).
+A **Svelte port** of [Streamdown](https://streamdown.ai/) by Vercel - an all in one markdown renderer, designed specifically for AI-powered streaming applications.
 
-## Creating a project
+## 📦 Installation
 
-If you're seeing this, you've probably already done this step. Congrats!
+```bash
+npm install svelte-streamdown
+# or
+pnpm add svelte-streamdown
+# or
+yarn add svelte-streamdown
+```
+
+## 🚀 Overview
+
+Perfect for AI-powered applications that need to stream and render markdown content safely and beautifully, with support for incomplete markdown blocks, security hardening, and rich features like code highlighting, math expressions, and interactive diagrams.
+
+## ✨ Main Features
+
+### 🎨 Built-in Typography Styles
+
+Beautiful, responsive typography with **built-in Tailwind CSS classes** for headings, lists, code blocks, and more. Comes with a complete default theme that works out of the box.
+
+### 📝 GitHub Flavored Markdown
+
+Full support for GitHub Flavored Markdown including:
+
+- Task lists
+- Tables
+- Strikethrough text
+
+### 💻 Interactive Code Blocks
+
+- Syntax highlighting powered by Shiki
+- Copy-to-clipboard functionality
+- Support any Shiki themes
+
+### 🔢 Mathematical Expressions
+
+LaTeX math support through KaTeX:
+
+- Perfect rendering for scientific content
+- Inline math: $E = mc^2$
+- Block math:
+
+$$
+\\sum_{i=1}^n x_i
+$$
+
+### 🧜‍♀️ Mermaid Diagrams
+
+- Render Mermaid diagrams from code blocks
+- **Incremental rendering** during streaming content
+- Pan and Zoom
+- Full screen mode
+
+**Example:**
+
+```mermaid
+graph TD
+    A[Start] --> B{Is it working?}
+    B -->|Yes| C[Great!]
+    B -->|No| D[Debug]
+    D --> B
+    C --> E[End]
+```
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Frontend
+    participant API
+    participant Database
+
+    User->>Frontend: Submit form
+    Frontend->>API: POST /api/data
+    API->>Database: INSERT query
+    Database-->>API: Success
+    API-->>Frontend: 200 OK
+    Frontend-->>User: Show success message
+```
+
+```mermaid
+pie title Project Time Allocation
+    "Development" : 45
+    "Testing" : 25
+    "Documentation" : 15
+    "Meetings" : 15
+```
+
+### Alert Support
+
+> [!IMPORTANT]
+> Native support for Github style Alert
+
+### 🔄 Streaming-Optimized
+
+- **Incomplete Markdown Parsing**: Handles unterminated blocks gracefully
+- **Progressive Rendering**: Perfect for streaming AI responses
+- **Real-time Updates**: Optimized for dynamic content
+
+### 🔒 Security Hardening
+
+- **Image Origin Control**: Whitelist allowed image sources
+- **Link Safety**: Control link destinations
+- **HTML Sanitization**: Prevent XSS attacks
+
+### 🎯 Fully Customizable Components & Theming
+
+- **Every component customizable** with Svelte snippets
+- **Granular theming system** - customize every part of every component
+- Override default styling and behavior for any markdown element
+- Full control over rendering with type-safe props
+- Seamless integration with your design system
+
+## 🔄 Differences from Original React Version
+
+This Svelte port maintains feature parity with the original [Streamdown](https://streamdown.ai/) while adapting to Svelte's patterns:
+
+| Aspect            | Original (React) | Svelte Port               |
+| ----------------- | ---------------- | ------------------------- |
+| **Framework**     | React            | Svelte 5                  |
+| **Component API** | JSX Components   | Svelte Snippets           |
+| **Styling**       | Tailwind CSS     | Tailwind CSS (compatible) |
+| **Context**       | React Context    | Svelte Context            |
+| **Build System**  | Vite/React       | Vite/SvelteKit            |
+| **TypeScript**    | Full TS support  | Full TS support           |
 
-```sh
-# create a new project in the current directory
-npx sv create
+### Tailwind CSS Setup
 
-# create a new project in my-app
-npx sv create my-app
+> [!NOTE]
+> Streamdown comes with **built-in Tailwind CSS classes** for beautiful default styling. To ensure all styles are included in your build, add the following to your `app.css` or main CSS file:
+
+```css
+@import 'tailwindcss';
+/* Add Streamdown styles to your Tailwind build */
+@source "../node_modules/svelte-streamdown/**/*";
 ```
 
-## Developing
+This ensures that all Streamdown's default styling is included in your Tailwind build process.
+
+> **Note:** This setup is primarily necessary if you're using Tailwind CSS v4's new `@source` directive or if you have aggressive purging enabled in older versions. If you're using standard Tailwind CSS v3+ with default purging, Streamdown's styles should be automatically included when the component is imported and used in your application.
+
+## 🚀 Quick Start
+
+### Basic Usage
+
+```svelte
+<script>
+	import { Streamdown } from 'svelte-streamdown';
 
-Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+	let content = `# Hello World
 
-```sh
-npm run dev
+This is a **bold** text and this is *italic*.
 
-# or start the server and open the app in a new browser tab
-npm run dev -- --open
+\`\`\`javascript
+console.log('Hello from Streamdown!');
+\`\`\`
+`;
+</script>
+
+<Streamdown {content} />
 ```
 
-Everything inside `src/lib` is part of your library, everything inside `src/routes` can be used as a showcase or preview app.
+### Advanced Usage with Custom Components
+
+```svelte
+<script>
+	import { Streamdown } from 'svelte-streamdown';
+
+	let content = `# Custom Components Example
+
+This heading will use a custom component!`;
 
-## Building
+	// Custom heading component
+</script>
 
-To build your library:
+{#snippet customH1({ children, props })}
+	<h1 class="mb-4 text-4xl font-bold text-blue-600" {...props}>
+		{children}
+	</h1>
+{/snippet}
 
-```sh
-npm pack
+<Streamdown {content} h1={customH1} />
 ```
 
-To create a production version of your showcase app:
+### Security Configuration
 
-```sh
-npm run build
+```svelte
+<script>
+	import { Streamdown } from 'svelte-streamdown';
+
+	let markdown = `![Safe Image](https://trusted-domain.com/image.jpg)
+[Safe Link](https://trusted-domain.com/page)`;
+</script>
+
+<Streamdown
+	{content}
+	allowedImagePrefixes={['https://trusted-domain.com']}
+	allowedLinkPrefixes={['https://trusted-domain.com']}
+/>
 ```
 
-You can preview the production build with `npm run preview`.
+## 📋 Props API
+
+| Prop                      | Type                                                  | Default          | Description                                    |
+| ------------------------- | ----------------------------------------------------- | ---------------- | ---------------------------------------------- |
+| `content`                 | `string`                                              | -                | **Required.** The markdown content to render   |
+| `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               |
+| `allowedLinkPrefixes`     | `string[]`                                            | `['*']`          | Allowed URL prefixes for links                 |
+| `allowedImagePrefixes`    | `string[]`                                            | `['*']`          | Allowed URL prefixes for images                |
+| `allowElement`            | `AllowElement \| null`                                | -                | Custom element filtering function              |
+| `allowedElements`         | `readonly string[] \| null`                           | -                | Whitelist of allowed HTML elements             |
+| `disallowedElements`      | `readonly string[] \| null`                           | -                | Blacklist of disallowed HTML elements          |
+| `skipHtml`                | `boolean`                                             | -                | Skip HTML parsing entirely                     |
+| `unwrapDisallowed`        | `boolean`                                             | -                | Unwrap instead of removing disallowed elements |
+| `urlTransform`            | `UrlTransform \| null`                                | -                | Custom URL transformation function             |
+| `theme`                   | `Partial<Theme>`                                      | -                | Custom theme overrides                         |
+| `baseTheme`               | `'tailwind' \| 'shadcn'`                              | `'tailwind'`     | Base theme to use before applying overrides    |
+| `mergeTheme`              | `boolean`                                             | `true`           | Whether to merge theme with base theme         |
+| `shikiTheme`              | `BundledTheme`                                        | `'github-light'` | Code highlighting theme                        |
+| `mermaidConfig`           | `MermaidConfig`                                       | -                | Mermaid diagram configuration                  |
+| `katexConfig`             | `KatexOptions \| ((inline: boolean) => KatexOptions)` | -                | KaTeX math rendering options                   |
+| `remarkPlugins`           | `PluggableList`                                       | -                | Additional remark plugins                      |
+| `rehypePlugins`           | `PluggableList`                                       | -                | Additional rehype plugins                      |
+| `remarkRehypeOptions`     | `RemarkRehypeOptions`                                 | -                | Remark-rehype conversion options               |
+| `customElements`          | `Record<string, Snippet<[ElementProps]>>`             | -                | Custom snippets for not handled nodes          |
+
+### Custom Component Props
+
+**Every single markdown element** can be customized with Svelte snippets, giving you complete control over styling and behavior:
 
-> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.
+```svelte
+<script>
+	import { Streamdown } from 'svelte-streamdown';
 
-## Publishing
+	let content = `# Fully Customizable
 
-Go into the `package.json` and give your package the desired name through the `"name"` option. Also consider adding a `"license"` field and point it to a `LICENSE` file which you can create from a template (one popular option is the [MIT license](https://opensource.org/license/mit/)).
+This heading uses a custom component with your design system!`;
+</script>
 
-To publish your library to [npm](https://www.npmjs.com):
+{#snippet customH1({ children, ...props })}
+	<h1
+		class="text-gradient mb-6 bg-gradient-to-r from-blue-600 to-purple-600 bg-clip-text text-4xl font-bold text-transparent"
+		{...props}
+	>
+		{@render children()}
+	</h1>
+{/snippet}
 
-```sh
-npm publish
+{#snippet customCode({ children, ...props })}
+	<code class="rounded bg-gray-100 px-2 py-1 font-mono text-sm dark:bg-gray-800" {...props}>
+		{@render children()}
+	</code>
+{/snippet}
+
+{#snippet customBlockquote({ children, ...props })}
+	<blockquote
+		class="border-l-4 border-blue-500 pl-4 text-gray-600 italic dark:text-gray-300"
+		{...props}
+	>
+		{@render children()}
+	</blockquote>
+{/snippet}
+
+<Streamdown {content} h1={customH1} code={customCode} blockquote={customBlockquote} />
 ```
+
+#### All Available Customizable Elements:
+
+**Text Elements**: `h1`, `h2`, `h3`, `h4`, `h5`, `h6`, `p`, `strong`, `em`, `del`
+
+**Links & Media**: `a`, `img`
+
+**Lists**: `ul`, `ol`, `li`
+
+**Code**: `code`, `inlineCode`, `pre`
+
+**Tables**: `table`, `thead`, `tbody`, `tr`, `th`, `td`
+
+**Special Content**: `blockquote`, `hr`, `alert`, `mermaid`, `math`, `inlineMath`
+
+**Note**: The above elements are **supported by Streamdown** and should be customized using individual props or the theme system. Use `customElements` only for HTML elements **not in this list** (like `div`, `span`, `section`, `article`, etc.).
+
+Each snippet receives `{ children, ...props }` where `props` contains all element attributes and classes.
+
+### Using `customElements` Record
+
+The `customElements` prop is specifically for HTML elements that are **not handled by the library by default**. For elements already supported by Streamdown (like `h1`, `p`, `code`, etc.), use individual props or the theme system instead.
+
+```svelte
+<script>
+	import { Streamdown } from 'svelte-streamdown';
+
+	let content = `# Custom Elements Example
+
+This content contains HTML elements not handled by Streamdown by default:
+
+<div class="special">This is a custom div element</div>
+
+<span class="highlight">This is a custom span element</span>
+
+<section class="wrapper">
+	<article>This is a custom article inside a section</article>
+</section>`;
+
+	// Define custom components for unsupported HTML elements
+</script>
+
+{#snippet customDiv({ children, props, className, node })}
+	<div class="rounded-lg border-2 border-blue-500 p-4 {className}" {...props}>
+		{@render children()}
+	</div>
+{/snippet}
+
+{#snippet customSpan({ children, props, className, node })}
+	<span class="rounded bg-yellow-200 px-2 py-1 {className}" {...props}>
+		{@render children()}
+	</span>
+{/snippet}
+
+{#snippet customSection({ children, props, className, node })}
+	<section class="my-8 rounded-xl bg-gray-50 p-6 {className}" {...props}>
+		{@render children()}
+	</section>
+{/snippet}
+
+{#snippet customArticle({ children, props, className, node })}
+	<article class="prose max-w-none {className}" {...props}>
+		{@render children()}
+	</article>
+{/snippet}
+
+<Streamdown
+	{content}
+	customElements={{
+		div: customDiv,
+		span: customSpan,
+		section: customSection,
+		article: customArticle
+	}}
+/>
+```
+
+### Benefits of `customElements`
+
+- **Handle Unsupported Elements**: Define components for HTML elements not built into Streamdown
+- **Semantic HTML Support**: Use elements like `<section>`, `<article>`, `<aside>`, `<nav>`, etc.
+- **Fallback Support**: Automatically handles unknown elements that would otherwise be ignored
+- **Type Safety**: Full TypeScript support with `ElementProps` interface
+
+### `customElements` vs Individual Props
+
+Use the right approach for the right elements:
+
+**Individual Props** (for supported Streamdown elements):
+
+```svelte
+<Streamdown {content} h1={customH1} p={customP} code={customCode} />
+```
+
+**CustomElements Record** (for unsupported HTML elements):
+
+```svelte
+<Streamdown
+	{content}
+	customElements={{ div: customDiv, span: customSpan, section: customSection }}
+/>
+```
+
+**Note**: For supported elements (h1, p, code, etc.), use individual props or the theme system. For unsupported elements (div, span, section, etc.), use `customElements`.
+
+## 🎨 Advanced Theming System
+
+### Built-in Themes
+
+Streamdown comes with two built-in themes:
+
+- **Default Theme**: The standard theme with gray-based colors
+- **Shadcn Theme**: A theme that uses shadcn/ui design tokens for seamless integration with shadcn-based projects
+
+Beyond custom snippets, Streamdown provides a **granular theming system** that lets you customize every part of every component without writing custom snippets. You can use the built-in themes (default and shadcn) or create completely custom themes using the `mergeTheme` utility.
+
+### Theme Structure
+
+Every component has multiple themeable parts. For example, the `code` component has:
+
+```typescript
+code: {
+  base: 'bg-gray-100 rounded p-2 font-mono text-sm',           // Main code block
+  container: 'my-4 w-full overflow-hidden rounded-xl border',   // Wrapper container
+  header: 'flex items-center justify-between bg-gray-100/80',  // Header with language
+  button: 'cursor-pointer p-1 text-gray-600 transition-all',   // Copy button
+  language: 'ml-1 font-mono lowercase',                        // Language label
+  pre: 'overflow-x-auto font-mono p-0 bg-gray-100/40'        // Pre element
+}
+```
+
+### Using Custom Themes
+
+```svelte
+<script>
+	import { Streamdown } from 'svelte-streamdown';
+
+	let content = `# Custom Theme Example
+
+\`\`\`javascript
+console.log('Beautiful code blocks!');
+\`\`\`
+
+> This blockquote is also themed
+
+| Header 1 | Header 2 |
+|----------|----------|
+| Cell 1   | Cell 2   |
+`;
+
+	// Custom theme overrides
+	let customTheme = {
+		code: {
+			container: 'my-6 rounded-2xl border-2 border-purple-200 shadow-lg',
+			header: 'bg-purple-50 text-purple-700 font-medium',
+			button: 'text-purple-600 hover:text-purple-800 hover:bg-purple-100'
+		},
+		blockquote: {
+			base: 'border-l-8 border-purple-400 bg-purple-50 p-4 italic text-purple-800'
+		},
+		table: {
+			base: 'border-purple-200 shadow-md',
+			container: 'my-6 rounded-lg overflow-hidden'
+		},
+		th: {
+			base: 'bg-purple-100 px-6 py-3 text-purple-900 font-bold'
+		},
+		td: {
+			base: 'px-6 py-3 border-purple-100'
+		}
+	};
+</script>
+
+<Streamdown {content} theme={customTheme} />
+```
+
+### All Themeable Components
+
+Each component supports multiple themeable parts:
+
+**Headings (`h1`-`h6`)**: `base`
+
+**Text Elements (`p`, `strong`, `em`, `del`)**: `base`
+
+**Lists (`ul`, `ol`, `li`)**: `base`
+
+**Links (`a`)**: `base`, `blocked` (for blocked/unsafe links)
+
+**Code (`code`)**: `base`, `container`, `header`, `button`, `language`, `skeleton`, `pre`
+
+**Inline Code (`inlineCode`)**: `base`
+
+**Images (`img`)**: `container`, `base`, `downloadButton`
+
+**Tables (`table`, `thead`, `tbody`, `tr`, `th`, `td`)**: `base`, `container` (table only)
+
+**Blockquotes (`blockquote`)**: `base`
+
+**Alerts (`alert`)**: `base`, `title`, `icon`, plus type-specific styles (`note`, `tip`, `warning`, `caution`, `important`)
+
+**Mermaid (`mermaid`)**: `base`, `downloadButton`
+
+**Math (`math`, `inlineMath`)**: `base`
+
+**Other (`hr`, `sup`, `sub`)**: `base`
+
+### Theme Merging
+
+Themes are intelligently merged using Tailwind's class merging utility, so you only need to override the specific parts you want to customize while keeping the default styling for everything else.
+
+## 🛠️ Development
+
+### Setup
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd svelte-streamdown
+
+# Install dependencies
+pnpm install
+
+# Start development server
+pnpm dev
+
+# Run tests
+pnpm test
+
+# Build for production
+pnpm build
+```
+
+### Building
+
+```bash
+# Build the library
+pnpm build
+
+# Preview the showcase app
+pnpm preview
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! This is a port of the original Streamdown project, so please:
+
+1. Check the [original Streamdown repository](https://github.com/vercel/streamdown) for upstream changes
+2. Ensure compatibility with the original API
+3. Maintain feature parity where possible
+4. Add tests for new features if you want
+
+## 📄 License
+
+MIT
+
+## 🙏 Acknowledgments
+
+- **Original Streamdown**: [Vercel](https://vercel.com) for creating the original React component
+- **Svelte Community**: For the amazing framework that made this port possible
+- **All Contributors**: For helping improve and maintain this project
+
+---
+
+Made with ❤️ and 🤖

package/dist/Elements/Code.svelte

@@ -12,7 +12,7 @@
 	let { node, className, props }: ElementProps = $props();
 
 	const streamdown = useStreamdown();
-	const themes = $derived(streamdown.shikiTheme);
+	const theme = $derived(streamdown.shikiTheme);
 	let codeContent = $derived((node.children[0] as any).value);
 	const language = $derived(node.properties.language as string);
 	const copy = useCopy({
@@ -36,9 +36,17 @@
 			console.error('Failed to download file:', error);
 		}
 	};
+
+	$effect(() => {
+		void highlighter.isReady(theme, language as any);
+	});
 </script>
 
-<div {...props} class={clsx(streamdown.theme.code.container, className)} data-language={language}>
+<div
+	{...props}
+	class={clsx(streamdown.theme.code.base, streamdown.theme.code.container, className)}
+	data-language={language}
+>
 	<div class={clsx(streamdown.theme.code.header)} data-code-block-header data-language={language}>
 		<span class={streamdown.theme.code.language}>{language}</span>
 		<div class="flex items-center gap-2">
@@ -57,34 +65,36 @@
 			</button>
 		</div>
 	</div>
-	<div style="height: fit-content; width: 100%;" class="relative overflow-visible">
-		<div class={streamdown.theme.code.base}>
-			{#await highlighter.isReady(themes, language as any)}
-				{@render Skeleton()}
-			{:then}
+	<div style="height: fit-content; width: 100%;" class={streamdown.theme.code.container}>
+		<div>
+			{#if highlighter.isLoaded(theme, language as any)}
 				{@const code = highlighter.highlightCode(
 					codeContent,
 					language as any,
-					themes,
+					theme,
 					streamdown.theme.code.pre
 				)}
 				{@html code}
-			{/await}
+			{:else}
+				{@render Skeleton()}
+			{/if}
 		</div>
 	</div>
 </div>
 
+<!-- Need to improve this -->
 {#snippet Skeleton()}
 	{@const lines = codeContent.split('\n')}
 	<!--  -->
-	<pre class={streamdown.theme.code.pre}><!--  -->
-<!--  --><code
-			><!--  -->{#each lines as line}<!--  --><span class={streamdown.theme.code.skeleton}
-					>{line}</span
-				><!--  -->
-<!--  -->{/each}<!--  --></code
-		><!--  -->
-						</pre>
+
+	<!--  --><code
+		class={streamdown.theme.code.pre}
+		style="height: fit-content; width: 100%; display: flex; flex-direction: column;"
+		><!--  -->{#each lines as line}<!--  --><span class={streamdown.theme.code.skeleton}
+				>{line}</span
+			><!--  -->
+			<!--  -->{/each}<!--  --></code
+	><!--  -->
 {/snippet}
 {#snippet copyIcon()}
 	<svg