@oml/markdown 0.13.0 → 0.14.0

package/src/static/browser-runtime.ts

@@ -7,6 +7,20 @@ const SUPPORTED = new Set(['table', 'tree', 'graph', 'chart', 'diagram', 'list',
 
 type ManifestEntry = { blockId: string; path: string };
 type WikilinkConfig = { linkingEnabled?: boolean };
+type HoverAnchorRect = {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+    width: number;
+    height: number;
+};
+
+let wikilinkPreviewCard: HTMLDivElement | undefined;
+let wikilinkPreviewHideTimer: number | undefined;
+let wikilinkPreviewRequestToken = 0;
+let tabPreviewModifierActive = false;
+let activeWikilinkHover: { link: HTMLAnchorElement; iri: string } | undefined;
 
 function parseJsonNode<T>(id: string, fallback: T): T {
     const node = document.getElementById(id);
@@ -189,6 +203,296 @@ function setupIriNavigationHandler(
     });
 }
 
+function isHoverPreviewEnabled(event: MouseEvent | undefined): boolean {
+    if (!event) {
+        return false;
+    }
+    return event.altKey || tabPreviewModifierActive;
+}
+
+function normalizeHoverAnchorRect(value: unknown): HoverAnchorRect | undefined {
+    if (!value || typeof value !== 'object') {
+        return undefined;
+    }
+    const obj = value as Record<string, unknown>;
+    if (typeof obj.left !== 'number' || typeof obj.right !== 'number' ||
+        typeof obj.top !== 'number' || typeof obj.bottom !== 'number' ||
+        typeof obj.width !== 'number' || typeof obj.height !== 'number') {
+        return undefined;
+    }
+    return {
+        left: obj.left,
+        right: obj.right,
+        top: obj.top,
+        bottom: obj.bottom,
+        width: obj.width,
+        height: obj.height,
+    };
+}
+
+function ensureWikilinkPreviewCard(): HTMLDivElement {
+    if (wikilinkPreviewCard) {
+        return wikilinkPreviewCard;
+    }
+    const card = document.createElement('div');
+    card.className = 'oml-wikilink-preview-card';
+    card.style.position = 'fixed';
+    card.style.zIndex = '1200';
+    card.style.display = 'none';
+    card.style.width = 'min(640px, calc(100vw - 48px))';
+    card.style.height = 'min(480px, calc(100vh - 48px))';
+    card.style.overflow = 'hidden';
+    card.style.padding = '0';
+    card.style.border = '1px solid var(--vscode-editorWidget-border, #c8ccd1)';
+    card.style.borderRadius = '10px';
+    card.style.background = 'var(--vscode-editor-background, #ffffff)';
+    card.style.color = 'var(--vscode-editor-foreground, #1f2328)';
+    card.style.boxShadow = '0 8px 24px rgb(0 0 0 / 24%)';
+    card.style.fontFamily = 'system-ui, -apple-system, Segoe UI, Roboto, sans-serif';
+    card.addEventListener('mouseenter', () => {
+        if (wikilinkPreviewHideTimer !== undefined) {
+            window.clearTimeout(wikilinkPreviewHideTimer);
+            wikilinkPreviewHideTimer = undefined;
+        }
+    });
+    // Don't hide on mouse leave - only ESC closes the preview now
+    document.body.appendChild(card);
+    wikilinkPreviewCard = card;
+    return card;
+}
+
+function scheduleHideWikilinkPreview(): void {
+    wikilinkPreviewRequestToken += 1;
+    if (wikilinkPreviewHideTimer !== undefined) {
+        window.clearTimeout(wikilinkPreviewHideTimer);
+        wikilinkPreviewHideTimer = undefined;
+    }
+    // Immediately hide the preview (no delay)
+    if (wikilinkPreviewCard) {
+        wikilinkPreviewCard.style.display = 'none';
+        wikilinkPreviewCard.replaceChildren();
+    }
+}
+
+async function scheduleIriPreview(
+    iri: string,
+    href: string,
+    anchorRect: HoverAnchorRect
+): Promise<void> {
+    if (wikilinkPreviewHideTimer !== undefined) {
+        window.clearTimeout(wikilinkPreviewHideTimer);
+        wikilinkPreviewHideTimer = undefined;
+    }
+    const token = ++wikilinkPreviewRequestToken;
+    await new Promise<void>((resolve) => window.setTimeout(resolve, 220));
+    if (token !== wikilinkPreviewRequestToken) {
+        return;
+    }
+    
+    const card = ensureWikilinkPreviewCard();
+    
+    // Create iframe to show the linked page
+    const iframe = document.createElement('iframe');
+    // Add preview mode parameter to prevent nested previews
+    const iframeSrc = new URL(href, window.location.href);
+    iframeSrc.searchParams.set('_oml_preview', '1');
+    iframe.src = iframeSrc.toString();
+    iframe.style.width = '100%';
+    iframe.style.height = '100%';
+    iframe.style.border = 'none';
+    iframe.style.borderRadius = '4px';
+    iframe.style.background = 'var(--vscode-editor-background, #ffffff)';
+    iframe.style.display = 'block';
+    
+    // Intercept clicks in the iframe to navigate the parent page
+    iframe.addEventListener('load', () => {
+        try {
+            const iframeDoc = iframe.contentDocument || iframe.contentWindow?.document;
+            if (!iframeDoc) {
+                return;
+            }
+            
+            // Remove download attributes from all links to prevent file downloads
+            const allLinks = iframeDoc.querySelectorAll('a[download]');
+            allLinks.forEach(link => link.removeAttribute('download'));
+            
+            // Add click listener to all links and interactive elements in the iframe
+            iframeDoc.addEventListener('click', (event) => {
+                const target = event.target;
+                if (!(target instanceof Element)) {
+                    return;
+                }
+                
+                const link = target.closest('a[href]');
+                if (!link || !(link instanceof HTMLAnchorElement)) {
+                    return;
+                }
+                
+                const linkHref = link.getAttribute('href');
+                if (!linkHref) {
+                    return;
+                }
+                
+                // Allow internal anchor links within the iframe
+                if (linkHref.startsWith('#')) {
+                    return;
+                }
+                
+                // Prevent any navigation in the iframe
+                event.preventDefault();
+                event.stopPropagation();
+                event.stopImmediatePropagation();
+                
+                // Get the absolute URL, accounting for any base URL in the iframe
+                const iframeLocation = iframe.contentWindow?.location.href;
+                const absoluteUrl = new URL(linkHref, iframeLocation || iframe.src);
+                
+                // Remove the preview parameter for the main navigation
+                absoluteUrl.searchParams.delete('_oml_preview');
+                
+                // Close the preview and navigate the parent page
+                scheduleHideWikilinkPreview();
+                
+                // Navigate the parent window (not the iframe)
+                const targetUrl = absoluteUrl.toString();
+                window.location.assign(targetUrl);
+                
+                return false;
+            }, true); // Use capture phase to catch events early
+        } catch (error) {
+            // If we can't access iframe content (CORS), silently fail
+            console.warn('Could not access iframe content for click interception:', error);
+        }
+    });
+    
+    card.replaceChildren(iframe);
+    card.style.display = 'block';
+    const cardRect = card.getBoundingClientRect();
+    const margin = 12;
+    const left = Math.min(
+        Math.max(16, anchorRect.left),
+        Math.max(16, window.innerWidth - cardRect.width - 16)
+    );
+    let top = anchorRect.bottom + margin;
+    if (top + cardRect.height > window.innerHeight - 16) {
+        top = Math.max(16, window.innerHeight - cardRect.height - 16);
+    }
+    card.style.left = `${left}px`;
+    card.style.top = `${top}px`;
+}
+
+function setupWikilinkHoverPreview(
+    wikilinkIndex: Record<string, string>,
+    iriAliasIndex: Record<string, string>,
+    linkingEnabled: boolean
+): void {
+    // Don't enable previews if we're already in preview mode (prevents nested previews)
+    const urlParams = new URLSearchParams(window.location.search);
+    if (urlParams.has('_oml_preview')) {
+        return;
+    }
+    
+    // Close preview when clicking anywhere outside the preview card
+    document.addEventListener('click', (event) => {
+        if (!wikilinkPreviewCard || wikilinkPreviewCard.style.display === 'none') {
+            return;
+        }
+        const target = event.target;
+        if (!(target instanceof Element)) {
+            return;
+        }
+        // Check if click is outside the preview card
+        if (!target.closest('.oml-wikilink-preview-card')) {
+            scheduleHideWikilinkPreview();
+            activeWikilinkHover = undefined;
+        }
+    }, true); // Use capture to catch clicks before they propagate
+    
+    // Handle hover events for wikilinks in text content
+    document.body.addEventListener('mouseover', (event) => {
+        const target = event.target instanceof Element
+            ? event.target
+            : (event.target instanceof Node ? event.target.parentElement : null);
+        if (!target || target.closest('.oml-wikilink-preview-card')) {
+            return;
+        }
+        const link = target.closest<HTMLAnchorElement>('a.wikilink[iri]');
+        if (!link) {
+            return;
+        }
+        const iri = link.getAttribute('iri')?.trim();
+        const href = link.getAttribute('href')?.trim();
+        if (!iri || !href || href === '#') {
+            return;
+        }
+        activeWikilinkHover = { link, iri };
+        if (isHoverPreviewEnabled(event)) {
+            void scheduleIriPreview(iri, href, link.getBoundingClientRect());
+        }
+    });
+
+    window.addEventListener('keydown', (event) => {
+        // ESC key closes the preview
+        if (event.key === 'Escape') {
+            scheduleHideWikilinkPreview();
+            activeWikilinkHover = undefined;
+            return;
+        }
+        
+        if (event.key === 'Tab') {
+            tabPreviewModifierActive = true;
+        }
+        if (!activeWikilinkHover) {
+            return;
+        }
+        if (!(event.altKey || event.key === 'Alt' || (event.key === 'Tab' && tabPreviewModifierActive))) {
+            return;
+        }
+        const link = activeWikilinkHover.link;
+        if (!link.isConnected || !link.matches(':hover')) {
+            return;
+        }
+        const href = link.getAttribute('href')?.trim();
+        if (!href || href === '#') {
+            return;
+        }
+        void scheduleIriPreview(activeWikilinkHover.iri, href, link.getBoundingClientRect());
+    });
+
+    window.addEventListener('keyup', (event) => {
+        if (event.key === 'Tab') {
+            tabPreviewModifierActive = false;
+        }
+    });
+
+    window.addEventListener('blur', () => {
+        tabPreviewModifierActive = false;
+    });
+
+    // Handle hover events dispatched by renderers (diagram, graph, table, etc.)
+    window.addEventListener('md-show-iri-hover', (event: Event) => {
+        if (!(event instanceof CustomEvent)) {
+            return;
+        }
+        const eventTarget = event.target;
+        if (eventTarget instanceof Element && eventTarget.closest('.oml-wikilink-preview-card')) {
+            return;
+        }
+        const detail = event.detail as { iri?: unknown; anchorRect?: unknown; previewEnabled?: unknown } | undefined;
+        const iri = typeof detail?.iri === 'string' ? detail.iri.trim() : '';
+        const anchorRect = normalizeHoverAnchorRect(detail?.anchorRect);
+        const previewEnabled = detail?.previewEnabled === true;
+        if (!iri || !anchorRect || !previewEnabled || !linkingEnabled) {
+            return;
+        }
+        const href = resolveWikiHref(iri, wikilinkIndex, iriAliasIndex);
+        if (!href || href === '#') {
+            return;
+        }
+        void scheduleIriPreview(iri, href, anchorRect);
+    });
+}
+
 function getMdKindFromCodeElement(code: Element): string | undefined {
     for (const className of Array.from(code.classList)) {
         if (!className.startsWith('language-')) {
@@ -229,6 +533,7 @@ async function applyExecutionResults(): Promise<void> {
     // Re-apply wikilinks for dynamic renderer re-renders (tables, filters, paging, etc.).
     installWikilinkObserver(wikilinkIndex, iriAliasIndex, linkingEnabled);
     setupIriNavigationHandler(wikilinkIndex, iriAliasIndex, linkingEnabled);
+    setupWikilinkHoverPreview(wikilinkIndex, iriAliasIndex, linkingEnabled);
 
     const manifest = parseJsonNode<ManifestEntry[]>('oml-md-block-manifest', []);
     if (!Array.isArray(manifest) || manifest.length === 0) {

package/src/static/markdown-webview.css

@@ -34,6 +34,19 @@ body {
   }
 }
 
+/* Hide OML code blocks until they're replaced by rendered panels to prevent flash of code */
+pre > code.language-table,
+pre > code.language-tree,
+pre > code.language-graph,
+pre > code.language-chart,
+pre > code.language-diagram,
+pre > code.language-list,
+pre > code.language-text,
+pre > code.language-matrix,
+pre > code.language-table-editor {
+  display: none;
+}
+
 h1,
 h2,
 h3,

package/src/static/runtime-assets.ts

@@ -172,4 +172,5 @@ export const STATIC_MARKDOWN_RUNTIME_CSS = `
 .oml-md-result .diagram-canvas-root svg {
   background: var(--vscode-editor-background, var(--oml-static-background, #ffffff));
 }
+
 `;

package/src/template/binder.ts

@@ -0,0 +1,70 @@
+// Copyright (c) 2026 Modelware. All rights reserved.
+
+import type { TemplateBindResult, TemplateDefinition, TemplateInvocationContext, TemplateParameterDefinition, TemplateValue } from './types.js';
+
+export function bindTemplateParameters(
+    template: TemplateDefinition,
+    context: TemplateInvocationContext,
+    explicitArgs: Readonly<Record<string, TemplateValue>> = {}
+): TemplateBindResult {
+    const values: Record<string, TemplateValue> = {};
+    const missingRequired: string[] = [];
+    const parameters = template.parameters ?? [];
+    for (const parameter of parameters) {
+        const explicit = explicitArgs[parameter.id];
+        if (explicit !== undefined) {
+            values[parameter.id] = explicit;
+            continue;
+        }
+        const bound = resolveValueFromContext(parameter, context);
+        if (bound !== undefined) {
+            values[parameter.id] = bound;
+            continue;
+        }
+        if (parameter.defaultValue !== undefined) {
+            values[parameter.id] = parameter.defaultValue;
+            continue;
+        }
+        if (parameter.required) {
+            missingRequired.push(parameter.id);
+        }
+    }
+    return { values, missingRequired };
+}
+
+function resolveValueFromContext(
+    parameter: TemplateParameterDefinition,
+    context: TemplateInvocationContext
+): TemplateValue | undefined {
+    switch (parameter.from) {
+        case 'context.member':
+            return context.focus?.memberIri;
+        case 'context.ontology':
+            return context.model?.ontologyIri;
+        case 'context.modelUri':
+            return context.model?.modelUri;
+        case 'context.selection[*]':
+            return context.selection?.iris ?? [];
+        default:
+            return resolveSelectionIndexedBinding(parameter.from, context);
+    }
+}
+
+function resolveSelectionIndexedBinding(
+    source: TemplateParameterDefinition['from'],
+    context: TemplateInvocationContext
+): TemplateValue | undefined {
+    if (!source || !source.startsWith('context.selection[')) {
+        return undefined;
+    }
+    const match = /^context\.selection\[(\d+)]$/.exec(source);
+    if (!match) {
+        return undefined;
+    }
+    const index = Number.parseInt(match[1] ?? '', 10);
+    if (!Number.isFinite(index) || index < 0) {
+        return undefined;
+    }
+    const iris = context.selection?.iris ?? [];
+    return iris[index];
+}

package/src/template/catalog.ts

@@ -0,0 +1,35 @@
+// Copyright (c) 2026 Modelware. All rights reserved.
+
+import type { TemplateDefinition } from './types.js';
+
+export interface TemplateCatalog {
+    readonly byId: ReadonlyMap<string, TemplateDefinition>;
+    readonly all: ReadonlyArray<TemplateDefinition>;
+}
+
+export function buildTemplateCatalog(templates: ReadonlyArray<TemplateDefinition>): TemplateCatalog {
+    const byId = new Map<string, TemplateDefinition>();
+    for (const template of templates) {
+        const id = normalizeTemplateId(template.id);
+        if (!id) {
+            continue;
+        }
+        byId.set(id, { ...template, id });
+    }
+    return {
+        byId,
+        all: [...byId.values()]
+    };
+}
+
+export function normalizeTemplateId(value: string): string {
+    return value.trim().replace(/^<|>$/g, '');
+}
+
+export function getTemplateById(catalog: TemplateCatalog, templateId: string): TemplateDefinition | undefined {
+    const normalized = normalizeTemplateId(templateId);
+    if (!normalized) {
+        return undefined;
+    }
+    return catalog.byId.get(normalized);
+}

package/src/template/compose.ts

@@ -0,0 +1,107 @@
+// Copyright (c) 2026 Modelware. All rights reserved.
+
+import { parse } from 'yaml';
+import type { TemplateBindingSource, TemplateValue } from './types.js';
+
+export interface TemplateComposeDirective {
+    id: string;
+    args: Record<string, TemplateValue>;
+    bind: Record<string, TemplateBindingSource>;
+}
+
+export function parseTemplateComposeDirective(source: string): TemplateComposeDirective | undefined {
+    const normalized = source.replace(/^\uFEFF/, '');
+    const frontMatterMatch = /^(---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*)([\s\S]*)$/.exec(normalized);
+    if (!frontMatterMatch) {
+        return undefined;
+    }
+    const trailing = frontMatterMatch[2] ?? '';
+    if (trailing.trim().length > 0) {
+        return undefined;
+    }
+    const yamlBody = frontMatterMatch[1]
+        .replace(/^---[ \t]*\r?\n/, '')
+        .replace(/\r?\n---[ \t]*$/, '');
+    const parsed = parse(yamlBody);
+    if (!isRecord(parsed)) {
+        return undefined;
+    }
+    const id = normalizeString(parsed.id);
+    if (!id) {
+        return undefined;
+    }
+    const args = parseArgs(parsed.args);
+    const bind = parseBind(parsed.bind);
+    return { id, args, bind };
+}
+
+function parseArgs(value: unknown): Record<string, TemplateValue> {
+    if (!isRecord(value)) {
+        return {};
+    }
+    const args: Record<string, TemplateValue> = {};
+    for (const [key, raw] of Object.entries(value)) {
+        const normalizedKey = normalizeString(key);
+        if (!normalizedKey) {
+            continue;
+        }
+        const converted = toTemplateValue(raw);
+        if (converted !== undefined) {
+            args[normalizedKey] = converted;
+        }
+    }
+    return args;
+}
+
+function parseBind(value: unknown): Record<string, TemplateBindingSource> {
+    if (!isRecord(value)) {
+        return {};
+    }
+    const bind: Record<string, TemplateBindingSource> = {};
+    for (const [key, raw] of Object.entries(value)) {
+        const normalizedKey = normalizeString(key);
+        const source = normalizeString(raw);
+        if (!normalizedKey || !source || !isTemplateBindingSource(source)) {
+            continue;
+        }
+        bind[normalizedKey] = source;
+    }
+    return bind;
+}
+
+function toTemplateValue(value: unknown): TemplateValue | undefined {
+    if (value === null) {
+        return null;
+    }
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.every((entry) => typeof entry === 'string') ? value : undefined;
+    }
+    if (isRecord(value)) {
+        return value;
+    }
+    return undefined;
+}
+
+function isTemplateBindingSource(value: string): value is TemplateBindingSource {
+    return value === 'context.member'
+        || value === 'context.ontology'
+        || value === 'context.modelUri'
+        || value === 'context.selection[*]'
+        || value === 'user'
+        || /^context\.selection\[\d+]$/.test(value);
+}
+
+function normalizeString(value: unknown): string | undefined {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const normalized = value.trim();
+    return normalized.length > 0 ? normalized : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}