Add component to render item documentation

package.json

@@ -53,6 +53,7 @@
 		"@sveltejs/package": "^2.0.0",
 		"@testing-library/jest-dom": "^6.1.5",
 		"@testing-library/svelte": "^4.0.5",
+		"@types/sanitize-html": "^2.9.5",
 		"@typescript-eslint/eslint-plugin": "^6.0.0",
 		"@typescript-eslint/parser": "^6.0.0",
 		"@vitest/coverage-v8": "^1.0.4",
@@ -73,5 +74,9 @@
 	},
 	"svelte": "./dist/index.js",
 	"types": "./dist/index.d.ts",
-	"type": "module"
+	"type": "module",
+	"dependencies": {
+		"marked": "^11.1.0",
+		"sanitize-html": "^2.11.0"
+	}
 }

src/lib/display/Doc.svelte

@@ -0,0 +1,27 @@
+<script lang="ts">
+	import type { Documentation } from '$lib/kiara.js';
+	import sanitizeHtml from 'sanitize-html';
+	import { marked } from 'marked';
+
+	export let doc: Documentation;
+	/**
+	 * Whether to show the full markdown documentation of the item, or just the summary
+	 */
+	export let verbose = true;
+
+	marked.use({
+		gfm: false
+	});
+
+	const emptyDocMarker = '-- n/a --';
+</script>
+
+{#if doc.description && doc.description !== emptyDocMarker}
+	<p>{doc.description}</p>
+{/if}
+
+{#if verbose && doc.doc}
+	{#await marked.parse(doc.doc) then html}
+		{@html sanitizeHtml(html)}
+	{/await}
+{/if}

src/lib/display/doc.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import { Doc } from '../index.js';
+import { render, screen } from '@testing-library/svelte';
+
+describe('Doc', () => {
+	const minimalDoc = {
+		description: '-- n/a --',
+		doc: null
+	};
+
+	const docWithMarkdown = {
+		description: 'Create an array of date objects from an array of strings.',
+		doc: 'This module is very simplistic at the moment, more functionality and options will be added in the future.\n\nAt its core, this module uses the standard parser from the\n[dateutil](https://github.com/dateutil/dateutil) package to parse strings into dates. '
+	};
+
+	const docWithMaliciousMarkdown = {
+		description: 'Bad',
+		doc: '<script>alert("hello world")</script>'
+	};
+	it('shows nothing if no meaningful documentation provided', () => {
+		render(Doc, { props: { doc: minimalDoc } });
+		// Don't render the n/a, it isn't useful to the end user
+		expect(screen.queryByText('-- n/a --')).toBeFalsy();
+	});
+
+	it('shows all available documentation by default', () => {
+		render(Doc, { props: { doc: docWithMarkdown } });
+		// description property is rendered as is
+		expect(screen.getByText(docWithMarkdown.description)).toBeInTheDocument();
+		// all the text from doc is rendered
+		expect(screen.getByText(/very simplistic/)).toBeInTheDocument();
+	});
+
+	it('only shows summary when verbose is false', () => {
+		render(Doc, { props: { doc: docWithMarkdown, verbose: false } });
+		// description property is rendered as is
+		expect(screen.getByText(docWithMarkdown.description)).toBeInTheDocument();
+		// all the text from doc is rendered
+		expect(screen.queryByText(/very simplistic/)).not.toBeInTheDocument();
+	});
+
+	it('renders markdown in the doc property', () => {
+		render(Doc, { props: { doc: docWithMarkdown } });
+		expect(screen.getByRole('link', { name: 'dateutil' })).toBeInTheDocument();
+	});
+
+	it('does not render malicious markdown in the doc property', () => {
+		render(Doc, { props: { doc: docWithMaliciousMarkdown } });
+		const theDom = document.body.innerHTML;
+		expect(theDom).toContain('Bad');
+		expect(theDom).not.toContain('script');
+	});
+});

src/lib/index.ts

@@ -1 +1 @@
-// Reexport your entry components here
+export { default as Doc } from './display/Doc.svelte';

src/lib/kiara.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Short description of the item
+ */
+export type Description = string;
+
+/**
+ * Detailed documentation of the item in markdown format
+ */
+export type Doc = string | null;
+
+/**
+ * Documentation about an item
+ */
+export interface Documentation {
+	description?: Description;
+	doc?: Doc;
+}