@lapis-notes/lapis-plugin-docs 0.0.0-stage → 0.1.0

package/dist/docs/DocsRichBlock.svelte

@@ -0,0 +1,291 @@
+<script lang="ts">
+	import AlertTriangleIcon from '@lucide/svelte/icons/alert-triangle';
+	import BookOpenIcon from '@lucide/svelte/icons/book-open';
+	import CheckCircle2Icon from '@lucide/svelte/icons/check-circle-2';
+	import Code2Icon from '@lucide/svelte/icons/code-2';
+	import FileTextIcon from '@lucide/svelte/icons/file-text';
+	import GraduationCapIcon from '@lucide/svelte/icons/graduation-cap';
+	import LightbulbIcon from '@lucide/svelte/icons/lightbulb';
+	import ListChecksIcon from '@lucide/svelte/icons/list-checks';
+	import MessageSquareIcon from '@lucide/svelte/icons/message-square';
+	import NotebookPenIcon from '@lucide/svelte/icons/notebook-pen';
+	import SparklesIcon from '@lucide/svelte/icons/sparkles';
+	import Table2Icon from '@lucide/svelte/icons/table-2';
+	import TrophyIcon from '@lucide/svelte/icons/trophy';
+	import StructuredTable from './candidates/StructuredTable.svelte';
+	import type { DocsCalloutTone, DocsRevisionBlock } from '../model';
+	import DocsMarkdownPreview from './DocsMarkdownPreview.svelte';
+	import { BLOCK_TYPE_LABELS } from './docs-workspace-helpers';
+
+	let {
+		block,
+		index,
+		sectionId,
+		headingIdPrefix = 'docs-heading',
+		extraClass = '',
+		dataDisplaySlideIndex = undefined,
+		sourcePath = ''
+	}: {
+		block: DocsRevisionBlock;
+		index: number;
+		sectionId?: string;
+		headingIdPrefix?: string;
+		extraClass?: string;
+		dataDisplaySlideIndex?: number;
+		sourcePath?: string;
+	} = $props();
+
+	const resolvedSectionId = $derived(sectionId ?? block.id);
+	const resolvedHeadingId = $derived(`${headingIdPrefix}-${block.id}`);
+	const markdownHeadingIdPrefix = $derived(`docs-md-${block.id}`);
+	const sectionClass = $derived(
+		[blockClass(block), extraClass].filter(Boolean).join(' ')
+	);
+	const renderedCodeMarkdown = $derived(
+		block.type === 'code' ? codeBlockMarkdown(block.language, block.code) : ''
+	);
+	const showHeader = $derived(!(block.type === 'markdown' && !block.title?.trim()));
+
+	function blockTitle(value: DocsRevisionBlock) {
+		return value.title?.trim() || BLOCK_TYPE_LABELS[value.type] || value.type;
+	}
+
+	function blockClass(value: DocsRevisionBlock) {
+		return `docs-rich-block docs-rich-block--${value.type}`;
+	}
+
+	function calloutLabel(tone: DocsCalloutTone) {
+		if (tone === 'critical') return 'Critical';
+		return tone[0].toUpperCase() + tone.slice(1);
+	}
+
+	function codeBlockMarkdown(language: string, code: string) {
+		const info = language.trim().split(/\s+/)[0]?.replace(/[^\w#+.-]/g, '') ?? '';
+		const fence = code.includes('```') ? '````' : '```';
+		return `${fence}${info ? info : ''}\n${code}\n${fence}`;
+	}
+</script>
+
+<section
+	class={sectionClass}
+	id={resolvedSectionId}
+	data-display-slide-index={dataDisplaySlideIndex}
+>
+	{#if showHeader}
+		<div class="docs-rich-block__header">
+			<div class="docs-rich-block__icon">
+				{#if block.type === 'concept'}
+					<LightbulbIcon aria-hidden="true" />
+				{:else if block.type === 'procedure'}
+					<ListChecksIcon aria-hidden="true" />
+				{:else if block.type === 'prompt'}
+					<MessageSquareIcon aria-hidden="true" />
+				{:else if block.type === 'code'}
+					<Code2Icon aria-hidden="true" />
+				{:else if block.type === 'table'}
+					<Table2Icon aria-hidden="true" />
+				{:else if block.type === 'callout'}
+					<AlertTriangleIcon aria-hidden="true" />
+				{:else if block.type === 'story'}
+					<TrophyIcon aria-hidden="true" />
+				{:else if block.type === 'resources'}
+					<BookOpenIcon aria-hidden="true" />
+				{:else if block.type === 'markdown'}
+					<NotebookPenIcon aria-hidden="true" />
+				{:else}
+					<FileTextIcon aria-hidden="true" />
+				{/if}
+			</div>
+			<div>
+				<p>{String(index + 1).padStart(2, '0')} / {BLOCK_TYPE_LABELS[block.type]}</p>
+				<h2
+					id={resolvedHeadingId}
+					data-cv-heading="true"
+					data-cv-heading-level="2"
+					data-cv-heading-title={blockTitle(block)}
+				>
+					{blockTitle(block)}
+				</h2>
+			</div>
+		</div>
+	{/if}
+
+	{#if block.type === 'concept'}
+		<div class="docs-rich-flow">
+			{#if block.summary}
+				<p class="docs-rich-lede">{block.summary}</p>
+			{/if}
+			{#if block.keyPoints.length}
+				<ul class="docs-rich-point-list">
+					{#each block.keyPoints as point (point)}
+						<li><CheckCircle2Icon aria-hidden="true" /> {point}</li>
+					{/each}
+				</ul>
+			{/if}
+			{#if block.details}
+				<DocsMarkdownPreview
+					{sourcePath}
+					value={block.details}
+					compact
+					headingIdPrefix={`${markdownHeadingIdPrefix}-details`}
+				/>
+			{/if}
+		</div>
+	{:else if block.type === 'procedure'}
+		<div class="docs-rich-steps">
+			{#each block.steps as step, stepIndex (step)}
+				<div class="docs-rich-step">
+					<span>{stepIndex + 1}</span>
+					<p>{step}</p>
+				</div>
+			{/each}
+		</div>
+		{#if block.notes}
+			<div class="docs-rich-note">
+				<SparklesIcon aria-hidden="true" />
+				<DocsMarkdownPreview
+					{sourcePath}
+					value={block.notes}
+					compact
+					headingIdPrefix={`${markdownHeadingIdPrefix}-notes`}
+				/>
+			</div>
+		{/if}
+	{:else if block.type === 'prompt'}
+		<div class="docs-rich-flow">
+			{#if block.problem}
+				<DocsMarkdownPreview
+					{sourcePath}
+					value={block.problem}
+					compact
+					headingIdPrefix={`${markdownHeadingIdPrefix}-problem`}
+				/>
+			{/if}
+			<div class="docs-rich-grid">
+				{#if block.requirements.length}
+					<div>
+						<h3>Requirements</h3>
+						<ul>{#each block.requirements as item (item)}<li>{item}</li>{/each}</ul>
+					</div>
+				{/if}
+				{#if block.traps.length}
+					<div>
+						<h3>Traps</h3>
+						<ul>{#each block.traps as item (item)}<li>{item}</li>{/each}</ul>
+					</div>
+				{/if}
+				{#if block.tests.length}
+					<div>
+						<h3>Good Tests</h3>
+						<ul>{#each block.tests as item (item)}<li>{item}</li>{/each}</ul>
+					</div>
+				{/if}
+			</div>
+			{#if block.approach}
+				<div class="docs-rich-panel">
+					<h3>Approach</h3>
+					<DocsMarkdownPreview
+						{sourcePath}
+						value={block.approach}
+						compact
+						headingIdPrefix={`${markdownHeadingIdPrefix}-approach`}
+					/>
+				</div>
+			{/if}
+			{#if block.answer}
+				<div class="docs-rich-panel docs-rich-panel--answer">
+					<h3>Answer</h3>
+					<DocsMarkdownPreview
+						{sourcePath}
+						value={block.answer}
+						compact
+						headingIdPrefix={`${markdownHeadingIdPrefix}-answer`}
+					/>
+				</div>
+			{/if}
+		</div>
+	{:else if block.type === 'code'}
+		{#if block.caption}
+			<p class="docs-rich-lede">{block.caption}</p>
+		{/if}
+		{#if block.code}
+			<DocsMarkdownPreview
+				{sourcePath}
+				value={renderedCodeMarkdown}
+				compact
+				floatingToc="off"
+				headingIdPrefix={`${markdownHeadingIdPrefix}-code`}
+			/>
+		{/if}
+	{:else if block.type === 'table'}
+		<StructuredTable columns={block.columns} rows={block.rows} />
+	{:else if block.type === 'callout'}
+		<div class={`docs-rich-callout docs-rich-callout--${block.tone}`}>
+			<strong>{calloutLabel(block.tone)}</strong>
+			<DocsMarkdownPreview
+				{sourcePath}
+				value={block.body}
+				compact
+				headingIdPrefix={`${markdownHeadingIdPrefix}-body`}
+			/>
+		</div>
+	{:else if block.type === 'story'}
+		<div class="docs-rich-story-grid">
+			{#each ['situation', 'task', 'action', 'result'] as field (field)}
+				{@const value = block[field as keyof typeof block] as string}
+				{#if value}
+					<div>
+						<h3>{field[0].toUpperCase() + field.slice(1)}</h3>
+						<p>{value}</p>
+					</div>
+				{/if}
+			{/each}
+		</div>
+		{#if block.useFor.length || block.metrics.length}
+			<div class="docs-rich-meta-grid">
+				{#if block.useFor.length}
+					<div><h3>Use For</h3><p>{block.useFor.join(', ')}</p></div>
+				{/if}
+				{#if block.metrics.length}
+					<div><h3>Metrics</h3><ul>{#each block.metrics as metric (metric)}<li>{metric}</li>{/each}</ul></div>
+				{/if}
+			</div>
+		{/if}
+	{:else if block.type === 'resources'}
+		<div class="docs-rich-resource-grid">
+			{#each block.items as item, itemIndex (itemIndex)}
+				<div class="docs-rich-resource">
+					<GraduationCapIcon aria-hidden="true" />
+					<div>
+						{#if item.url}
+							<a href={item.url}>{item.title || item.url}</a>
+						{:else}
+							<strong>{item.title}</strong>
+						{/if}
+						{#if item.kind || item.notes}
+							<p>{[item.kind, item.notes].filter(Boolean).join(' - ')}</p>
+						{/if}
+					</div>
+				</div>
+			{/each}
+		</div>
+	{:else if block.type === 'markdown'}
+		{#if block.body}
+			<DocsMarkdownPreview
+				{sourcePath}
+				value={block.body}
+				compact
+				headingIdPrefix={`${markdownHeadingIdPrefix}-body`}
+			/>
+		{/if}
+	{:else}
+		{#if block.body}
+			<DocsMarkdownPreview
+				{sourcePath}
+				value={block.body}
+				compact
+				headingIdPrefix={`${markdownHeadingIdPrefix}-body`}
+			/>
+		{/if}
+	{/if}
+</section>

package/dist/docs/DocsRichBlock.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { DocsRevisionBlock } from '../model';
+type $$ComponentProps = {
+    block: DocsRevisionBlock;
+    index: number;
+    sectionId?: string;
+    headingIdPrefix?: string;
+    extraClass?: string;
+    dataDisplaySlideIndex?: number;
+    sourcePath?: string;
+};
+declare const DocsRichBlock: import("svelte").Component<$$ComponentProps, {}, "">;
+type DocsRichBlock = ReturnType<typeof DocsRichBlock>;
+export default DocsRichBlock;

package/dist/docs/DocsRichDisplay.svelte

@@ -0,0 +1,316 @@
+<script lang="ts">
+	import BookOpenIcon from '@lucide/svelte/icons/book-open';
+	import Rows3Icon from '@lucide/svelte/icons/rows-3';
+	import TargetIcon from '@lucide/svelte/icons/target';
+	import MarkdownFloatingToc from './candidates/MarkdownFloatingToc.svelte';
+	import { pinReadingChrome } from './pin-reading-chrome';
+	import type {
+		DocsBookChapterNavigation,
+		DocsBookNavigation as DocsBookNavigationModel,
+		DocsNote,
+		DocsRevisionBlock
+	} from '../model';
+	import DocsBookNavigation from './DocsBookNavigation.svelte';
+	import DocsChapterFooter from './DocsChapterFooter.svelte';
+	import DocsChapterScrollRing from './DocsChapterScrollRing.svelte';
+	import DocsMarkdownPreview from './DocsMarkdownPreview.svelte';
+	import DocsRichBlock from './DocsRichBlock.svelte';
+	import {
+		clampDisplaySlideIndex,
+		displayFocusSelector,
+		readVisibleDisplaySlideIndex
+	} from './docs-display-focus';
+	import { BLOCK_TYPE_LABELS, DOC_TYPE_LABELS } from './docs-workspace-helpers';
+
+	let {
+		note,
+		focusSlideIndex = 0,
+		bookNavigation = null,
+		chapterNavigation = null,
+		saving = false,
+		onFocusSlideIndexChange = () => {},
+		onToggleChapterComplete = () => {},
+		onOpenNote = () => {}
+	}: {
+		note: DocsNote;
+		focusSlideIndex?: number;
+		bookNavigation?: DocsBookNavigationModel | null;
+		chapterNavigation?: DocsBookChapterNavigation | null;
+		saving?: boolean;
+		onFocusSlideIndexChange?: (index: number) => void;
+		onToggleChapterComplete?: (completed: boolean) => void | Promise<void>;
+		onOpenNote?: (noteId: string) => void;
+	} = $props();
+
+	let documentElement = $state<HTMLElement | null>(null);
+	let ignoreObserver = false;
+	let lastScrolledIndex = $state<number | null>(null);
+	let trackedNoteId = $state<string | null>(null);
+	let chapterScrollPercent = $state(0);
+
+	const outline = $derived(
+		note.blocks
+			.map((block, index) => ({
+				id: block.id,
+				title: blockTitle(block),
+				type: BLOCK_TYPE_LABELS[block.type] ?? block.type,
+				index: index + 1,
+				include: !(block.type === 'markdown' && !block.title?.trim())
+			}))
+			.filter((item) => item.include)
+	);
+	const appendixTitle = $derived(note.blocks.length ? 'Additional Notes' : 'Notes');
+	const appendixSlideIndex = $derived(note.blocks.length + 1);
+	const activeBookNavigation = $derived(bookNavigation ?? null);
+	const showReadingChrome = $derived(Boolean(chapterNavigation && activeBookNavigation));
+
+	function blockTitle(block: DocsRevisionBlock) {
+		return block.title?.trim() || BLOCK_TYPE_LABELS[block.type] || block.type;
+	}
+
+	function scrollParentFor(element: HTMLElement) {
+		const viewport = element.closest('[data-slot="scroll-area"]')?.querySelector(
+			'[data-slot="scroll-area-viewport"]'
+		);
+		if (viewport instanceof HTMLElement) return viewport;
+
+		let current = element.parentElement;
+		while (current) {
+			const style = getComputedStyle(current);
+			if (/(auto|scroll)/.test(style.overflowY)) return current;
+			current = current.parentElement;
+		}
+		return null;
+	}
+
+	function readChapterScrollPercent(scrollRoot: Element | null) {
+		if (!scrollRoot || !(scrollRoot instanceof HTMLElement)) return 0;
+		const maxScroll = scrollRoot.scrollHeight - scrollRoot.clientHeight;
+		if (maxScroll <= 0) return scrollRoot.scrollHeight > scrollRoot.clientHeight ? 0 : 100;
+		return Math.max(0, Math.min(100, (scrollRoot.scrollTop / maxScroll) * 100));
+	}
+
+	function scrollToFocusIndex(index: number) {
+		const root = documentElement;
+		if (!root) return;
+		const scrollRoot = scrollParentFor(root);
+		ignoreObserver = true;
+		lastScrolledIndex = index;
+		// Aligning the hero with scrollIntoView leaves content padding scrolled away
+		// (~1% on long notes). Reset the viewport for the intro slide instead.
+		if (index === 0) {
+			if (scrollRoot) scrollRoot.scrollTop = 0;
+		} else {
+			const target = root.querySelector<HTMLElement>(displayFocusSelector(note, index));
+			target?.scrollIntoView({ block: 'start', behavior: 'auto' });
+		}
+		requestAnimationFrame(() => {
+			ignoreObserver = false;
+			chapterScrollPercent = readChapterScrollPercent(scrollRoot);
+		});
+	}
+
+	function publishVisibleIndex() {
+		const root = documentElement;
+		if (!root || ignoreObserver) return;
+		const scrollRoot = scrollParentFor(root);
+		const next = readVisibleDisplaySlideIndex(root, scrollRoot);
+		if (next === focusSlideIndex) return;
+		lastScrolledIndex = next;
+		onFocusSlideIndexChange(next);
+	}
+
+	$effect(() => {
+		const root = documentElement;
+		const noteId = note.id;
+		const index = clampDisplaySlideIndex(focusSlideIndex, note);
+		if (!root) return;
+
+		// Note switches reuse this component and the ScrollArea viewport, so always
+		// reset scroll when the note changes — even if focus is already slide 0.
+		if (trackedNoteId !== noteId) {
+			trackedNoteId = noteId;
+			lastScrolledIndex = null;
+			const scrollRoot = scrollParentFor(root);
+			if (scrollRoot) scrollRoot.scrollTop = 0;
+			chapterScrollPercent = 0;
+			if (index === 0) {
+				lastScrolledIndex = 0;
+				return;
+			}
+		}
+
+		if (lastScrolledIndex === index) return;
+		scrollToFocusIndex(index);
+	});
+
+	$effect(() => {
+		const root = documentElement;
+		if (!root) return;
+		const scrollRoot = scrollParentFor(root);
+		let allowFocusPublish = false;
+		let frame = 0;
+
+		const updateScrollProgress = () => {
+			chapterScrollPercent = readChapterScrollPercent(scrollRoot);
+		};
+
+		const onScroll = () => {
+			if (frame) cancelAnimationFrame(frame);
+			frame = requestAnimationFrame(() => {
+				frame = 0;
+				updateScrollProgress();
+				if (!allowFocusPublish) return;
+				publishVisibleIndex();
+			});
+		};
+		scrollRoot?.addEventListener('scroll', onScroll, { passive: true });
+		updateScrollProgress();
+
+		const resizeObserver =
+			scrollRoot && typeof ResizeObserver !== 'undefined'
+				? new ResizeObserver(() => updateScrollProgress())
+				: null;
+		if (scrollRoot && resizeObserver) resizeObserver.observe(scrollRoot);
+
+		// Only track scroll after mount so a restored slide focus is not
+		// immediately overwritten by the initial layout pass.
+		const timer = setTimeout(() => {
+			allowFocusPublish = true;
+			updateScrollProgress();
+		}, 0);
+
+		return () => {
+			clearTimeout(timer);
+			if (frame) cancelAnimationFrame(frame);
+			resizeObserver?.disconnect();
+			scrollRoot?.removeEventListener('scroll', onScroll);
+		};
+	});
+</script>
+
+<article class="docs-rich-document" bind:this={documentElement}>
+	<div class="docs-reading-anchor" use:pinReadingChrome>
+		<div class="docs-reading-edge">
+			{#if showReadingChrome}
+				<DocsChapterScrollRing {chapterScrollPercent} />
+			{/if}
+			<MarkdownFloatingToc root={documentElement} />
+		</div>
+		{#if activeBookNavigation?.chapters.length}
+			<DocsBookNavigation
+				variant="floating"
+				book={activeBookNavigation}
+				activeNoteId={note.id}
+				{chapterNavigation}
+				{onOpenNote}
+			/>
+		{/if}
+	</div>
+	<header class="docs-rich-hero" data-display-slide-index="0">
+		<div class="docs-rich-hero__eyebrow">
+			<BookOpenIcon aria-hidden="true" />
+			<span>{DOC_TYPE_LABELS[note.docType] ?? note.docType}</span>
+		</div>
+		<h1
+			id={`docs-heading-${note.id}`}
+			data-cv-heading="true"
+			data-cv-heading-level="1"
+			data-cv-heading-title={note.title}
+		>
+			{note.title}
+		</h1>
+		{#if note.summary}
+			<p class="docs-rich-hero__summary">{note.summary}</p>
+		{/if}
+		{#if note.learningGoal}
+			<div class="docs-rich-goal">
+				<TargetIcon aria-hidden="true" />
+				<div>
+					<span>Learning Goal</span>
+					<p>{note.learningGoal}</p>
+				</div>
+			</div>
+		{/if}
+		{#if note.tags.length}
+			<div class="docs-rich-tags" aria-label="Tags">
+				{#each note.tags as tag (tag)}
+					<span>#{tag}</span>
+				{/each}
+			</div>
+		{/if}
+	</header>
+
+	{#if bookNavigation?.indexNoteId === note.id && bookNavigation.chapters.length}
+		<DocsBookNavigation variant="toc" book={bookNavigation} activeNoteId={note.id} {onOpenNote} />
+	{/if}
+
+	{#if outline.length}
+		<nav class="docs-rich-outline" aria-label="Document outline">
+			<div>
+				<p>We'll Cover</p>
+				<span>{outline.length} sections</span>
+			</div>
+			<ol>
+				{#each outline as item (item.id)}
+					<li>
+						<a href={`#${item.id}`}>
+							<span>{item.index}</span>
+							<strong>{item.title}</strong>
+							<small>{item.type}</small>
+						</a>
+					</li>
+				{/each}
+			</ol>
+		</nav>
+	{/if}
+
+	<div class="docs-rich-blocks">
+		{#each note.blocks as block, index (block.id)}
+			<DocsRichBlock
+				{block}
+				{index}
+				dataDisplaySlideIndex={index + 1}
+				sourcePath={note.sourcePath}
+			/>
+		{/each}
+	</div>
+
+	{#if note.body}
+		<section
+			class="docs-rich-block docs-rich-block--text docs-rich-additional"
+			data-display-slide-index={appendixSlideIndex}
+		>
+			<div class="docs-rich-block__header">
+				<div class="docs-rich-block__icon"><Rows3Icon aria-hidden="true" /></div>
+				<div>
+					<p>Appendix</p>
+					<h2
+						id={`docs-heading-${note.id}-appendix`}
+						data-cv-heading="true"
+						data-cv-heading-level="2"
+						data-cv-heading-title={appendixTitle}
+					>
+						{appendixTitle}
+					</h2>
+				</div>
+			</div>
+			<DocsMarkdownPreview
+				value={note.body}
+				floatingToc="off"
+				sourcePath={note.sourcePath}
+				headingIdPrefix={`docs-md-${note.id}-appendix`}
+			/>
+		</section>
+	{/if}
+
+	{#if showReadingChrome && chapterNavigation}
+		<DocsChapterFooter
+			{note}
+			{chapterNavigation}
+			{saving}
+			onToggleComplete={onToggleChapterComplete}
+			{onOpenNote}
+		/>
+	{/if}
+</article>

package/dist/docs/DocsRichDisplay.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { DocsBookChapterNavigation, DocsBookNavigation as DocsBookNavigationModel, DocsNote } from '../model';
+type $$ComponentProps = {
+    note: DocsNote;
+    focusSlideIndex?: number;
+    bookNavigation?: DocsBookNavigationModel | null;
+    chapterNavigation?: DocsBookChapterNavigation | null;
+    saving?: boolean;
+    onFocusSlideIndexChange?: (index: number) => void;
+    onToggleChapterComplete?: (completed: boolean) => void | Promise<void>;
+    onOpenNote?: (noteId: string) => void;
+};
+declare const DocsRichDisplay: import("svelte").Component<$$ComponentProps, {}, "">;
+type DocsRichDisplay = ReturnType<typeof DocsRichDisplay>;
+export default DocsRichDisplay;