@dominikcz/greg 0.9.27

package/src/lib/MarkdownDocs/TreeView.svelte

@@ -0,0 +1,32 @@
+<script lang="ts">
+	import TreeViewItem from "./TreeViewItem.svelte";
+	import type { TreeViewItem as TreeViewItemType } from "./treeViewTypes";
+
+	interface TreeViewProps {
+		tree: TreeViewItemType[];
+		active: string;
+		class?: string;
+		navigate: (path: string) => void;
+	}
+	let {
+		tree,
+		active = "",
+		class: className = "",
+		navigate,
+	}: TreeViewProps = $props();
+</script>
+
+<ul class="tree-view {className}">
+	{#each tree as item (item.link || item.label)}
+		<TreeViewItem {item} depth={0} {active} {navigate} />
+	{/each}
+</ul>
+
+<style>
+	.tree-view {
+		margin: 0;
+		list-style: none;
+		padding-inline-start: 0;
+		user-select: none;
+	}
+</style>

package/src/lib/MarkdownDocs/TreeViewItem.svelte

@@ -0,0 +1,219 @@
+<script module lang="ts">
+	// based on https://svelte.dev/playground/82b00644720a4ca2bdb89c6a653ec987
+	// retain module scoped expansion state for each tree node
+	const _expansionState = new Map<string, boolean>();
+</script>
+
+<script lang="ts">
+	import Self from "./TreeViewItem.svelte";
+	import type { TreeViewItem } from "./treeViewTypes";
+	import { ChevronRight } from "@lucide/svelte";
+	import { withBase } from "./common";
+
+	interface TreeViewItemProps {
+		item: TreeViewItem;
+		active: string;
+		depth: number;
+		navigate: (path: string) => void;
+	}
+	let {
+		item,
+		active = "",
+		depth = 0,
+		navigate,
+	}: TreeViewItemProps = $props();
+
+	const EXTERNAL_RE = /^(?:[a-z][a-z\d+\-.]*:|\/\/)/i;
+
+	// Inicjalizacja stanu rozwinięcia
+	let expanded = $state(false);
+	// Automatycznie rozwiń jeśli aktywna ścieżka jest w tej gałęzi
+	let shouldExpand = $derived(
+		active.startsWith(item.link) && item.link !== active,
+	);
+	$effect(() => {
+		if (shouldExpand && !expanded) expanded = true;
+	});
+
+	function toggle() {
+		_expansionState.set(item.link, !expanded);
+		expanded = !expanded;
+	}
+
+	function shouldHandleWithRouter() {
+		if (!item.link) return false;
+		if (EXTERNAL_RE.test(item.link)) return false;
+		if (item.target && item.target !== "_self") return false;
+		return true;
+	}
+
+	function handleClick(e: MouseEvent) {
+		if (item.target === "_blank") {
+			e.preventDefault();
+			window.open(item.link, "_blank", "noopener,noreferrer");
+			return;
+		}
+
+		if (!shouldHandleWithRouter()) return;
+		e.preventDefault();
+		navigate(item.link);
+	}
+
+	function handleToggleClick(e: MouseEvent) {
+		if (item.target === "_blank") {
+			e.preventDefault();
+			window.open(item.link, "_blank", "noopener,noreferrer");
+			return;
+		}
+
+		if (!shouldHandleWithRouter()) return;
+		e.preventDefault();
+		toggle();
+		navigate(item.link);
+	}
+</script>
+
+<li>
+	{#if item.children.length}
+		<a
+			href={withBase(item.link)}
+			target={item.target}
+			rel={item.rel}
+			onclick={handleToggleClick}
+			class="arrow"
+			class:active={active == item.link}
+		>
+			<span class="chevron" class:expanded>
+				<ChevronRight />
+			</span>
+			{#if item.status}<span class={item.status}
+				></span>{/if}{item.label}{#if item.badge}<span
+					class="nav-badge {item.badge.type ?? 'tip'}"
+					>{item.badge.text}</span
+				>{/if}
+		</a>
+		{#if expanded}
+			<ul>
+				{#each item.children as child}
+					<Self item={child} depth={depth + 1} {active} {navigate} />
+				{/each}
+			</ul>
+		{/if}
+	{:else}
+		<a
+			href={withBase(item.link)}
+			target={item.target}
+			rel={item.rel}
+			class="no-arrow"
+			class:active={active == item.link}
+			onclick={handleClick}
+			>{#if item.status}<span class={item.status}
+				></span>{/if}{item.label}{#if item.badge}<span
+					class="nav-badge {item.badge.type ?? 'tip'}"
+					>{item.badge.text}</span
+				>{/if}</a
+		>
+	{/if}
+</li>
+
+<style lang="scss">
+	li {
+		line-height: 1.5rem;
+		margin: 0.1rem 0;
+	}
+
+	ul {
+		list-style: none;
+		padding-inline-start: 0.85rem;
+		margin: 0.1rem 0 0 0.6rem;
+		border-left: 1px solid var(--greg-border-color);
+	}
+
+	.no-arrow {
+		padding-left: 1.1rem;
+	}
+
+	.arrow {
+		cursor: pointer;
+		display: flex;
+
+		.chevron {
+			display: flex;
+			align-items: center;
+			transition: transform 0.2s ease;
+			transform: rotate(0deg);
+			flex-shrink: 0;
+
+			&.expanded {
+				transform: rotate(90deg);
+			}
+		}
+	}
+
+	a {
+		padding: 0.3rem 0.5rem;
+		display: block;
+		text-decoration: none;
+		color: var(--greg-menu-color);
+		border-radius: 5px;
+		font-size: 0.875rem;
+		line-height: 1.5rem;
+
+		span {
+			vertical-align: bottom;
+		}
+
+		&:hover {
+			background-color: var(--greg-menu-hover-background);
+			color: var(--greg-color);
+		}
+
+		&.active {
+			background-color: var(--greg-accent-light);
+			color: var(--greg-accent);
+			font-weight: 600;
+
+			.arrow {
+				color: var(--greg-accent);
+			}
+
+			&:hover {
+				background-color: var(--greg-accent-light);
+			}
+		}
+	}
+
+	.nav-badge {
+		display: inline-block;
+		margin-left: 0.4rem;
+		padding: 0 7px;
+		border-radius: 10px;
+		font-size: 11px;
+		font-weight: 500;
+		line-height: 18px;
+		vertical-align: middle;
+		white-space: nowrap;
+		border: 1px solid transparent;
+
+		&.tip {
+			background-color: var(--greg-tip-bg);
+			border-color: var(--greg-tip-border);
+			color: var(--greg-tip-text);
+		}
+		&.info {
+			background-color: var(--greg-info-bg);
+			border-color: var(--greg-info-border);
+			color: var(--greg-info-text);
+		}
+		&.warning {
+			background-color: var(--greg-warning-bg);
+			border-color: var(--greg-warning-border);
+			color: var(--greg-warning-text);
+		}
+		&.danger {
+			background-color: var(--greg-danger-bg);
+			border-color: var(--greg-danger-border);
+			color: var(--greg-danger-text);
+		}
+	}
+</style>

package/src/lib/MarkdownDocs/VersionOutdatedNotice.svelte

@@ -0,0 +1,72 @@
+<script lang="ts">
+    type Props = {
+        currentTitle: string;
+        defaultTitle: string;
+        message?: string;
+        actionLabel?: string;
+        onGoToDefault: () => void;
+    };
+
+    let {
+        currentTitle,
+        defaultTitle,
+        message = "",
+        actionLabel = "Go to latest",
+        onGoToDefault,
+    }: Props = $props();
+
+    const resolvedMessage = $derived(
+        String(message || "").trim() ||
+            `You are viewing an older documentation version (${currentTitle}). ${defaultTitle} is currently recommended.`,
+    );
+</script>
+
+<div class="version-notice" role="status" aria-live="polite">
+    <p>{resolvedMessage}</p>
+    <button type="button" onclick={onGoToDefault}>{actionLabel}</button>
+</div>
+
+<style lang="scss">
+    .version-notice {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: 0.75rem;
+        padding: 0.55rem 1.25rem;
+        border-bottom: 1px solid color-mix(in srgb, var(--greg-accent) 25%, var(--greg-border-color));
+        background: color-mix(in srgb, var(--greg-accent-light) 55%, var(--greg-header-background));
+        color: var(--greg-color);
+        flex-shrink: 0;
+
+        p {
+            margin: 0;
+            font-size: 0.86rem;
+            line-height: 1.35;
+        }
+
+        button {
+            border: 1px solid color-mix(in srgb, var(--greg-accent) 45%, var(--greg-border-color));
+            background: var(--greg-header-background);
+            color: var(--greg-accent);
+            font: inherit;
+            font-size: 0.8rem;
+            font-weight: 600;
+            border-radius: 6px;
+            padding: 0.25rem 0.55rem;
+            cursor: pointer;
+
+            &:hover {
+                border-color: var(--greg-accent);
+                background: var(--greg-accent-light);
+            }
+        }
+    }
+
+    @media (max-width: 800px) {
+        .version-notice {
+            flex-direction: column;
+            align-items: flex-start;
+            padding: 0.55rem 0.75rem;
+        }
+    }
+</style>

package/src/lib/MarkdownDocs/__tests__/codeDirectives.test.js

@@ -0,0 +1,54 @@
+import { describe, it, expect } from 'vitest';
+import { parseCodeDirectives, decorateHighlightedCodeHtml } from '../codeDirectives.js';
+import { normalizeCodeFenceInfo } from '../codeFenceInfo.js';
+
+describe('codeDirectives', () => {
+	it('parses meta line ranges and strips inline code markers', () => {
+		const parsed = parseCodeDirectives('const a = 1; // [!code ++]\nconst token = a;', '{2} [demo.ts]');
+		expect(parsed.cleanedCode).toContain('const a = 1;');
+		expect(parsed.cleanedCode).not.toContain('[!code');
+		expect(parsed.lineInfo[0].diffAdd).toBe(true);
+		expect(parsed.lineInfo[1].highlight).toBe(true);
+	});
+
+	it('decorates line wrappers with classes', () => {
+		const directives = parseCodeDirectives('const oldValue = 1; // [!code --]\nconst token = oldValue; // [!code focus]', '{1}');
+		const html = '<pre><code><span class="line">const oldValue = 1;</span>\n<span class="line">const token = oldValue;</span></code></pre>';
+		const out = decorateHighlightedCodeHtml(html, directives);
+
+		expect(out).toContain('line highlighted diff remove');
+		expect(out).toContain('line focused');
+		expect(out).toContain('has-focused-lines');
+	});
+
+	it('does not strip markers inside markdown source fences', () => {
+		const parsed = parseCodeDirectives('const oldValue = 1; // [!code --]\n', '', 'md');
+		expect(parsed.cleanedCode).toContain('[!code --]');
+		expect(parsed.cleanedCode.endsWith('\n')).toBe(false);
+		expect(parsed.lineInfo).toEqual([]);
+	});
+
+	it('supports line numbers metadata with custom start index', () => {
+		const parsed = parseCodeDirectives('const a = 1;\nconst b = 2;', 'line-numbers=10', 'ts');
+		expect(parsed.lineNumbers).toEqual({ enabled: true, start: 10 });
+
+		const html = '<pre><code><span class="line">const a = 1;</span>\n<span class="line">const b = 2;</span></code></pre>';
+		const out = decorateHighlightedCodeHtml(html, parsed);
+		expect(out).toContain('data-line-numbers="true"');
+		expect(out).toContain('data-line="10"');
+		expect(out).toContain('data-line="11"');
+	});
+
+	it('enables line numbers with default start when no index is provided', () => {
+		const parsed = parseCodeDirectives('const a = 1;', 'line-numbers', 'ts');
+		expect(parsed.lineNumbers).toEqual({ enabled: true, start: 1 });
+	});
+
+	it('normalizes vitepress-style lang/meta forms', () => {
+		expect(normalizeCodeFenceInfo('ts{2}', '')).toEqual({ lang: 'ts', meta: '{2}' });
+		expect(normalizeCodeFenceInfo('ts:line-numbers=10', '{1}')).toEqual({
+			lang: 'ts',
+			meta: '{1} line-numbers=10',
+		});
+	});
+});

package/src/lib/MarkdownDocs/__tests__/common.test.js

@@ -0,0 +1,41 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { pathConfig, withoutBase } from '../common';
+
+function setConfig(config) {
+    Object.assign(pathConfig, config);
+}
+
+beforeEach(() => {
+    setConfig({ base: '/greg/', srcDir: 'my_docs', docsBase: 'documentation' });
+});
+
+describe('common.withoutBase', () => {
+    it('maps {base}/{docsBase}/... to {srcDir}/... when all fields are set', () => {
+        setConfig({ base: '/greg/', srcDir: 'my_docs', docsBase: 'documentation' });
+
+        expect(withoutBase('/greg/documentation/guide/getting-started')).toBe('/documentation/guide/getting-started');
+        expect(withoutBase('/greg/documentation')).toBe('/documentation');
+    });
+
+    it('keeps old base-strip behavior for paths outside /{base}/{docsBase}', () => {
+        setConfig({ base: '/greg/', srcDir: 'my_docs', docsBase: 'documentation' });
+
+        expect(withoutBase('/greg/guide/getting-started')).toBe('/guide/getting-started');
+        expect(withoutBase('/something-else/guide')).toBe('/something-else/guide');
+    });
+
+    it('supports base="/" and still maps /{docsBase} to {srcDir}', () => {
+        setConfig({ base: '/', srcDir: 'content_docs', docsBase: 'documentation' });
+
+        expect(withoutBase('/documentation/guide/intro')).toBe('/documentation/guide/intro');
+        expect(withoutBase('/content_docs/guide/intro')).toBe('/content_docs/guide/intro');
+    });
+
+    it('keeps external URLs and relative paths unchanged', () => {
+        setConfig({ base: '/greg/', srcDir: 'my_docs', docsBase: 'documentation' });
+
+        expect(withoutBase('https://example.com/docs')).toBe('https://example.com/docs');
+        expect(withoutBase('guide/getting-started')).toBe('guide/getting-started');
+    });
+});

package/src/lib/MarkdownDocs/__tests__/docsExamplesLint.test.js

@@ -0,0 +1,77 @@
+import { describe, it, expect } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const DOCS_MARKDOWN_DIR = path.join(process.cwd(), 'docs', 'guide', 'markdown');
+
+function isMdExampleFenceStart(line) {
+	return /^`{3,4}md\b/.test(line.trim());
+}
+
+function isFenceClose(line, tickCount) {
+	return new RegExp(`^\\s*${'`'.repeat(tickCount)}\\s*$`).test(line);
+}
+
+function findMdExampleViolations(content) {
+	const lines = content.split(/\r?\n/);
+	const violations = [];
+
+	for (let i = 0; i < lines.length; i++) {
+		const startLine = lines[i].trim();
+		if (!isMdExampleFenceStart(startLine)) continue;
+
+		const tickCount = (startLine.match(/^`+/) ?? [''])[0].length;
+		let closeIdx = -1;
+		for (let j = i + 1; j < lines.length; j++) {
+			if (isFenceClose(lines[j], tickCount)) {
+				closeIdx = j;
+				break;
+			}
+		}
+
+		if (closeIdx === -1) {
+			violations.push(`Line ${i + 1}: unclosed markdown example fence`);
+			continue;
+		}
+
+		let cursor = closeIdx + 1;
+		let hasOutput = false;
+		for (; cursor < lines.length; cursor++) {
+			const line = lines[cursor].trim();
+			if (/^Output\b/i.test(line)) {
+				hasOutput = true;
+				break;
+			}
+			if (isMdExampleFenceStart(line)) break;
+		}
+
+		if (!hasOutput) {
+			violations.push(`Line ${i + 1}: missing Output section after markdown example`);
+		}
+
+		i = closeIdx;
+	}
+
+	return violations;
+}
+
+describe('docs lint - markdown examples', () => {
+	it('ensures every md source example has an Output section', async () => {
+		const entries = await fs.readdir(DOCS_MARKDOWN_DIR, { withFileTypes: true });
+		const mdFiles = entries
+			.filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+			.map((entry) => path.join(DOCS_MARKDOWN_DIR, entry.name));
+
+		const failures = [];
+
+		for (const filePath of mdFiles) {
+			const content = await fs.readFile(filePath, 'utf8');
+			const violations = findMdExampleViolations(content);
+			for (const violation of violations) {
+				failures.push(`${path.relative(process.cwd(), filePath)}: ${violation}`);
+			}
+		}
+
+		expect(failures, failures.join('\n')).toEqual([]);
+	});
+});

package/src/lib/MarkdownDocs/__tests__/fixtures/docs/markdown/__partial-basic.md

@@ -0,0 +1,3 @@
+### Configuration
+
+Can be created using `.foorc.json`.

package/src/lib/MarkdownDocs/__tests__/fixtures/docs/markdown/snippet.js

@@ -0,0 +1,9 @@
+function foo() {
+    return 42;
+}
+export default foo;
+
+// #region snippet
+// region snippet line 1
+..
+// #endregion snippet

package/src/lib/MarkdownDocs/__tests__/fixtures/includes/part.md

@@ -0,0 +1,11 @@
+## Included section
+
+Some **bold** text.
+
+::: info
+Included container.
+:::
+
+### Nested part
+
+Nested content.

package/src/lib/MarkdownDocs/__tests__/fixtures/includes/wrapper.md

@@ -0,0 +1,5 @@
+Before include.
+
+<!--@include: ./part.md#included-section-->
+
+After include.

package/src/lib/MarkdownDocs/__tests__/fixtures/snippets/sample.js

@@ -0,0 +1,8 @@
+const one = 1;
+const two = 2;
+const three = 3;
+
+// #region demo
+console.log('region line 1');
+console.log('region line 2');
+// #endregion demo

package/src/lib/MarkdownDocs/__tests__/fixtures/snippets/sample.md

@@ -0,0 +1,5 @@
+## Snippet heading
+
+::: info
+This should stay raw when imported with <<<
+:::

package/src/lib/MarkdownDocs/__tests__/helpers.js

@@ -0,0 +1,67 @@
+/**
+ * Test helpers — builds a unified processor matching svelte.config.js setup,
+ * but outputs plain HTML (no Svelte compilation).
+ */
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkRehype from 'remark-rehype';
+import rehypeStringify from 'rehype-stringify';
+import rehypeSlug from 'rehype-slug';
+import rehypeAutolinkHeadings from 'rehype-autolink-headings';
+import rehypeCodeGroup from '../rehypeCodeGroup.js';
+import rehypeCodeTitle from '../rehypeCodeTitle.js';
+import { remarkContainers, rehypeContainers } from '../remarkContainers.js';
+import { rehypeTocPlaceholder } from '../rehypeToc.js';
+import { remarkCodeMeta } from '../remarkCodeMeta.js';
+import { remarkImports } from '../remarkImports.js';
+
+const defaultImportsOptions = { sourceRoot: globalThis.process.cwd(), docsDir: 'docs' };
+
+// Single shared processor — created once so shiki's lazy grammar loading
+// only happens on first call, not per-test.
+let _processor = null;
+
+async function getProcessor(opts = {}) {
+	// If custom options are passed, build a one-off processor
+	if (opts.containers || opts.toc || opts.imports) {
+		return unified()
+			.use(remarkParse)
+			.use(remarkImports, opts.imports ?? defaultImportsOptions)
+			.use(remarkCodeMeta)
+			.use(remarkContainers, opts.containers ?? {})
+			.use(remarkRehype, { allowDangerousHtml: true })
+			.use(rehypeSlug)
+			.use(rehypeAutolinkHeadings, { behavior: 'prepend', properties: { class: 'header-anchor', ariaHidden: 'true', tabIndex: -1 }, content: { type: 'text', value: '#' } })
+			.use(rehypeContainers, opts.containers ?? {})
+			.use(rehypeCodeGroup)
+			.use(rehypeCodeTitle)
+			.use(rehypeTocPlaceholder, opts.toc ?? {})
+			.use(rehypeStringify, { allowDangerousHtml: true });
+	}
+	if (!_processor) {
+		_processor = unified()
+			.use(remarkParse)
+			.use(remarkImports, defaultImportsOptions)
+			.use(remarkCodeMeta)
+			.use(remarkContainers)
+			.use(remarkRehype, { allowDangerousHtml: true })
+			.use(rehypeSlug)
+			.use(rehypeAutolinkHeadings, { behavior: 'prepend', properties: { class: 'header-anchor', ariaHidden: 'true', tabIndex: -1 }, content: { type: 'text', value: '#' } })
+			.use(rehypeContainers)
+			.use(rehypeCodeGroup)
+			.use(rehypeCodeTitle)
+			.use(rehypeTocPlaceholder)
+			.use(rehypeStringify, { allowDangerousHtml: true });
+	}
+	return _processor;
+}
+
+export async function process(markdown, opts = {}) {
+	const processor = await getProcessor(opts);
+	const input = opts.vfile
+		? { ...opts.vfile, value: markdown }
+		: opts.filename
+			? { value: markdown, path: opts.filename }
+			: markdown;
+	return String(await processor.process(input));
+}