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

package/README.md

@@ -1,3 +1,189 @@
-# Temporary Holding Version
+# `@lapis-notes/lapis-plugin-docs`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/lapismd/lapis-plugin-docs/actions/workflows/ci.yml/badge.svg)](https://github.com/lapismd/lapis-plugin-docs/actions/workflows/ci.yml)
+[![Storybook Pages](https://github.com/lapismd/lapis-plugin-docs/actions/workflows/publish-storybook-pages.yml/badge.svg)](https://github.com/lapismd/lapis-plugin-docs/actions/workflows/publish-storybook-pages.yml)
+[![Storybook](https://img.shields.io/badge/storybook-live-ff4785?logo=storybook&logoColor=white)](https://lapismd.github.io/lapis-plugin-docs/)
+
+First-party external Docs plugin for Lapis. It provides vault-native
+`*.doc.md` notes, ordered books, linked knowledge, cards, and FSRS review
+through public Lapis and Design Core surfaces inside the host workspace.
+
+The plugin owns the Docs domain model, document view, sidebar, cards, review,
+settings, and native `--ui-docs-*` styling. Hosts own plugin loading, vault
+state, persistence, and application policy.
+
+[![Docs workspace](registry-assets/banner.preview.png)](registry-assets/banner.full.png)
+
+<details>
+<summary>Plugin screenshots</summary>
+
+[![Structured reading](registry-assets/gallery/reading.preview.png)](registry-assets/gallery/reading.full.png)
+
+[![Cards workspace](registry-assets/gallery/cards.preview.png)](registry-assets/gallery/cards.full.png)
+
+</details>
+
+## Current package status
+
+- Package version: `@lapis-notes/lapis-plugin-docs@0.1.0`.
+- Runtime plugin id: `docs`.
+- Runtime peers: `@lapis-notes/api@^0.2.6`,
+  `@lapismd/design-core@^0.12.1`, `@lapismd/mira@~0.1.4`,
+  `@lapismd/mira-editor@~0.0.3`, and `svelte@5.56.10`.
+- Canonical repository: `lapismd/lapis-plugin-docs`.
+- Live catalog: <https://lapismd.github.io/lapis-plugin-docs/>.
+- Canonical requirements live in `spec/src/plugins/docs/`; verification
+  status is tracked in `spec/src/verification.md`.
+
+## Install
+
+Hosts load the plugin class through the Lapis plugin lifecycle. `onload`
+registers the Docs projection, document and sidebar views, commands, ribbon,
+and settings.
+
+```sh
+pnpm add @lapis-notes/lapis-plugin-docs
+```
+
+Import the plugin stylesheet once at the application boundary:
+
+```ts
+import "@lapis-notes/lapis-plugin-docs/styles.css";
+```
+
+## Runtime surfaces
+
+| Surface | Entry | Use for |
+| --- | --- | --- |
+| Docs document | `*.doc.md` exclusive editor-view contribution | Structured editing, reading, slides, cards, and note-scoped review |
+| Docs sidebar | Movable `docs` workspace view | Browse notes, folders, links, tags, due cards, and review queues |
+| Projection | `docs/note` | Index Docs metadata and content from the configured vault root |
+| Cards | Basic and cloze card panels | Create cards, inspect references, and manage scheduling metadata |
+| Review | FSRS-backed note and workspace queues | Study due cards and persist review outcomes to the source note |
+| Import | Lazy Anki package reader | Import supported `.apkg` collections and media into the vault |
+| Settings | Versioned plugin data | Configure the Docs root, which defaults to `docs` |
+
+## Document and review coverage
+
+Docs files are ordinary Markdown with YAML front matter. The filesystem is
+authoritative: books order their chapters, wiki links and tags form a graph,
+and review state travels with each card in its source document. Structured
+reading uses the host `MarkdownRenderer` when available and public Mira
+preview as the fallback.
+
+The bundled sample book exercises structured blocks, Mermaid diagrams,
+slides, links, tags, basic and cloze cards, due queues, and FSRS history. The
+same deterministic fixtures power the package Storybook and the committed
+README screenshots.
+
+## Styling contract
+
+The plugin uses native CSS, Design Core semantic tokens, and Docs-owned
+`docs-` classes with `--ui-docs-*` custom properties. Production sources stay
+free of Tailwind utility strings (`pnpm check:no-tailwind`).
+
+1. Import `@lapis-notes/lapis-plugin-docs/styles.css` once.
+2. Theme through Design Core tokens and Docs custom properties.
+3. Keep package-owned surfaces independent of host-private selectors.
+
+## Layout conventions
+
+```text
+src/
+  lib/            plugin class, views, repository, domain model, native CSS
+  stories/        App-backed shell, placement, and registry capture stories
+fixtures/
+  sample-docs/    deterministic *.doc.md Storybook corpus
+spec/
+  src/            canonical specification and verification evidence
+```
+
+## Usage example
+
+A Docs document is Markdown with structured front matter:
+
+```markdown
+---
+id: spaced-repetition
+title: Spaced repetition
+docType: revision
+tags:
+  - learning/memory
+cards:
+  - id: retrieval-practice
+    type: basic
+    status: active
+    prompt: Why use retrieval practice?
+    answer: Recalling an idea strengthens access to it.
+---
+
+# Spaced repetition
+
+Review material shortly before it would otherwise be forgotten.
+```
+
+## Storybook and local documentation
+
+Run the local catalog (defaults to port 7040):
+
+```sh
+pnpm storybook
+pnpm storybook:stop
+pnpm storybook:restart
+```
+
+Build the static catalog:
+
+```sh
+pnpm build-storybook
+```
+
+`Plugins/Docs/Registry Screenshots` contains the deterministic workspace,
+reading, and cards states used to refresh the committed README media. These
+capture stories are intentionally separate from visual-regression baselines.
+
+The canonical specification lives in `spec/src`. Validate it after protected
+source, story, or presentation changes:
+
+```sh
+pnpm exec spec-validator search "Storybook"
+pnpm spec:check
+```
+
+### CI and local parity
+
+CI runs specification, quality, unit, package, static Storybook, and sharded
+Storybook interaction lanes on every pull request and push to `main`. The
+static catalog is published to GitHub Pages from `main`.
+
+`pnpm test:storybook` runs the Storybook Vitest project with Playwright.
+Interaction and accessibility behaviour stays executable in the capture
+stories; screenshot files are generated from their completed states.
+
+## Release and validation
+
+Common validation commands:
+
+```sh
+pnpm spec:first
+pnpm spec:check
+pnpm check
+pnpm test
+pnpm build
+pnpm publint
+pnpm test:storybook
+pnpm build-storybook
+```
+
+## Further reading
+
+| Resource | Use |
+| --- | --- |
+| [`spec/src/plugins/docs/index.md`](./spec/src/plugins/docs/index.md) | Canonical plugin ownership and package requirements |
+| [`spec/src/plugins/docs/runtime.md`](./spec/src/plugins/docs/runtime.md) | Runtime, sidebar, Storybook, and import behaviour |
+| [`spec/src/plugins/docs/notes.md`](./spec/src/plugins/docs/notes.md) | Document model and reading behaviour |
+| [`spec/src/plugins/docs/cards.md`](./spec/src/plugins/docs/cards.md) | Cards and review behaviour |
+| [`spec/src/spec-governance.md`](./spec/src/spec-governance.md) | Governance, validation, and discovery rules |
+| [`spec/src/verification.md`](./spec/src/verification.md) | Requirement verification evidence |
+| [`AGENTS.md`](./AGENTS.md) | Contributor and agent workflow |
+| [`PROVENANCE.md`](./PROVENANCE.md) | Component provenance and exclusions |

package/dist/docs/DocsBlockMarkdownEditor.svelte

@@ -0,0 +1,37 @@
+<script lang="ts">
+  /**
+   * Block Markdown field. Document-mode MarkdownComposer replaces the
+   * CodeMirror markdown editor for prose and section bodies.
+   */
+  import DocsMarkdownField from "./DocsMarkdownField.svelte";
+
+  let {
+    value = $bindable(""),
+    placeholder = "Write with Markdown...",
+    ariaLabel = "Markdown block",
+    minRows: _minRows = 8,
+    compact: _compact = true,
+    floatingToc: _floatingToc = "off" as const,
+    sourcePath: _sourcePath = "",
+    attachmentUpload: _attachmentUpload,
+  }: {
+    value?: string;
+    placeholder?: string;
+    ariaLabel?: string;
+    minRows?: number;
+    compact?: boolean;
+    floatingToc?: "auto" | "off" | "always";
+    sourcePath?: string;
+    attachmentUpload?: unknown;
+  } = $props();
+</script>
+
+<DocsMarkdownField
+  {value}
+  label={ariaLabel}
+  showLabel={false}
+  {placeholder}
+  onChange={(next) => {
+    value = next;
+  }}
+/>

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

@@ -0,0 +1,13 @@
+type $$ComponentProps = {
+    value?: string;
+    placeholder?: string;
+    ariaLabel?: string;
+    minRows?: number;
+    compact?: boolean;
+    floatingToc?: "auto" | "off" | "always";
+    sourcePath?: string;
+    attachmentUpload?: unknown;
+};
+declare const DocsBlockMarkdownEditor: import("svelte").Component<$$ComponentProps, {}, "value">;
+type DocsBlockMarkdownEditor = ReturnType<typeof DocsBlockMarkdownEditor>;
+export default DocsBlockMarkdownEditor;

package/dist/docs/DocsBlockRefPicker.svelte

@@ -0,0 +1,75 @@
+<script lang="ts">
+  import { ReferencePicker } from "@lapismd/design-core/forms";
+  import {
+    docsBlockIdFromRef,
+    docsBlockReferenceIndex,
+    docsBlockRefMarker,
+  } from "../model/docs-card-context";
+  import type { DocsRevisionBlock } from "../model";
+
+  let {
+    blocks,
+    refs,
+    addOpen = $bindable(false),
+    onAddOpenChange = () => {},
+    onChange,
+  }: {
+    blocks: DocsRevisionBlock[];
+    refs: string[];
+    addOpen?: boolean;
+    onAddOpenChange?: (open: boolean) => void;
+    onChange: (refs: string[]) => void;
+  } = $props();
+
+  const referenceIndex = $derived(docsBlockReferenceIndex(blocks));
+  const pickerRefs = $derived(refs.map((id) => docsBlockRefMarker(id)));
+</script>
+
+<ReferencePicker
+  refs={pickerRefs}
+  {referenceIndex}
+  {addOpen}
+  addLabel="Add block"
+  addHeading="Block"
+  searchPlaceholder="Search note blocks..."
+  emptyLabel="No matching blocks."
+  unresolvedLabel="Missing block"
+  unresolvedDescription="This block is no longer on the note."
+  {onAddOpenChange}
+  onChange={(next) => onChange(next.map((ref) => docsBlockIdFromRef(ref)))}
+>
+  {#snippet searchOption(reference)}
+    <span class="docs-block-ref-option">
+      <span class="docs-block-ref-option__title">{reference.label}</span>
+      {#if reference.excerpt}
+        <span class="docs-block-ref-option__snippet">{reference.excerpt}</span>
+      {/if}
+    </span>
+  {/snippet}
+</ReferencePicker>
+
+<style>
+  .docs-block-ref-option {
+    display: grid;
+    min-width: 0;
+    gap: 0.1rem;
+  }
+
+  .docs-block-ref-option__title {
+    overflow: hidden;
+    color: var(--foreground);
+    font-size: 0.75rem;
+    font-weight: 650;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .docs-block-ref-option__snippet {
+    overflow: hidden;
+    color: var(--muted-foreground);
+    font-size: 0.72rem;
+    line-height: 1.35;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+</style>

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

@@ -0,0 +1,11 @@
+import type { DocsRevisionBlock } from "../model";
+type $$ComponentProps = {
+    blocks: DocsRevisionBlock[];
+    refs: string[];
+    addOpen?: boolean;
+    onAddOpenChange?: (open: boolean) => void;
+    onChange: (refs: string[]) => void;
+};
+declare const DocsBlockRefPicker: import("svelte").Component<$$ComponentProps, {}, "addOpen">;
+type DocsBlockRefPicker = ReturnType<typeof DocsBlockRefPicker>;
+export default DocsBlockRefPicker;

package/dist/docs/DocsBookEditor.svelte

@@ -0,0 +1,141 @@
+<script lang="ts">
+	import PlusIcon from '@lucide/svelte/icons/plus';
+	import { EntryActions, type SearchableChoiceOption } from '@lapismd/design-core/forms';
+	import SearchableChoicePicker from './candidates/SearchableChoicePicker.svelte';
+	import { slugifyDocsId } from '../model/markdown';
+	import type { DocsBookMetadata } from '../model';
+
+	let {
+		book,
+		noteOptions = [],
+		onChange = () => {}
+	}: {
+		book: DocsBookMetadata;
+		noteOptions?: SearchableChoiceOption[];
+		onChange?: (book: DocsBookMetadata) => void;
+	} = $props();
+
+	function normalizeChapterId(value: string) {
+		const trimmed = value.trim();
+		if (!trimmed) return '';
+		return slugifyDocsId(trimmed, trimmed);
+	}
+
+	function setChapters(chapters: DocsBookMetadata['chapters']) {
+		onChange({ chapters });
+	}
+
+	function patchChapter(chapterIndex: number, noteId: string) {
+		setChapters(
+			book.chapters.map((chapter, index) =>
+				index === chapterIndex ? { noteId } : chapter
+			)
+		);
+	}
+
+	function addChapter() {
+		setChapters([...book.chapters, { noteId: '' }]);
+	}
+
+	function removeChapter(chapterIndex: number) {
+		setChapters(book.chapters.filter((_, index) => index !== chapterIndex));
+	}
+
+	function moveChapter(chapterIndex: number, direction: -1 | 1) {
+		const targetIndex = chapterIndex + direction;
+		if (targetIndex < 0 || targetIndex >= book.chapters.length) return;
+		const nextChapters = [...book.chapters];
+		const [chapter] = nextChapters.splice(chapterIndex, 1);
+		nextChapters.splice(targetIndex, 0, chapter);
+		setChapters(nextChapters);
+	}
+</script>
+
+<div class="docs-book-editor">
+	{#each book.chapters as chapter, chapterIndex (chapterIndex)}
+		<EntryActions
+			index={chapterIndex}
+			total={book.chapters.length}
+			removeLabel={`Remove chapter ${chapter.noteId || chapterIndex + 1}`}
+			onMove={(direction) => moveChapter(chapterIndex, direction)}
+			onRemove={() => removeChapter(chapterIndex)}
+		>
+			<div class="docs-book-editor__row">
+				<span>{chapterIndex + 1}</span>
+				<SearchableChoicePicker
+					value={chapter.noteId}
+					options={noteOptions}
+					placeholder="Select note"
+					searchPlaceholder="Search notes..."
+					emptyLabel="No notes found."
+					ariaLabel={`Book chapter ${chapterIndex + 1}`}
+					normalize={normalizeChapterId}
+					onChange={(noteId) => patchChapter(chapterIndex, noteId)}
+				/>
+			</div>
+		</EntryActions>
+	{/each}
+	<button type="button" class="docs-book-editor__add" onclick={addChapter}>
+		<PlusIcon aria-hidden="true" />
+		<span>Add chapter</span>
+	</button>
+</div>
+
+<style>
+	.docs-book-editor {
+		display: grid;
+		gap: 0.4rem;
+		width: 100%;
+		min-width: 0;
+	}
+
+	.docs-book-editor__row {
+		display: grid;
+		grid-template-columns: 1.6rem minmax(0, 1fr);
+		align-items: center;
+		gap: 0.55rem;
+		min-width: 0;
+		padding-block: 0.2rem;
+	}
+
+	.docs-book-editor__row > span {
+		display: grid;
+		width: 1.35rem;
+		height: 1.35rem;
+		place-items: center;
+		border-radius: 999px;
+		background: color-mix(in srgb, currentColor 8%, transparent);
+		color: var(--muted-foreground);
+		font-size: 0.72rem;
+		font-weight: 650;
+		line-height: 1;
+	}
+
+	.docs-book-editor__add {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		gap: 0.35rem;
+		width: 100%;
+		min-height: 2.1rem;
+		border: 1px dashed var(--border);
+		border-radius: 0.4rem;
+		background: transparent;
+		color: var(--muted-foreground);
+		font-size: 0.82rem;
+		font-weight: 650;
+		cursor: pointer;
+	}
+
+	.docs-book-editor__add:hover,
+	.docs-book-editor__add:focus-visible {
+		border-color: var(--ring);
+		color: var(--foreground);
+		outline: 0;
+	}
+
+	.docs-book-editor__add :global(svg) {
+		width: 0.95rem;
+		height: 0.95rem;
+	}
+</style>

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

@@ -0,0 +1,10 @@
+import { type SearchableChoiceOption } from '@lapismd/design-core/forms';
+import type { DocsBookMetadata } from '../model';
+type $$ComponentProps = {
+    book: DocsBookMetadata;
+    noteOptions?: SearchableChoiceOption[];
+    onChange?: (book: DocsBookMetadata) => void;
+};
+declare const DocsBookEditor: import("svelte").Component<$$ComponentProps, {}, "">;
+type DocsBookEditor = ReturnType<typeof DocsBookEditor>;
+export default DocsBookEditor;