@oml/markdown 0.13.0 → 0.14.0

package/src/template/definition.ts

@@ -0,0 +1,222 @@
+// Copyright (c) 2026 Modelware. All rights reserved.
+
+import { extractLeadingFrontMatter } from '../md/md-frontmatter.js';
+import type {
+    TemplateDefinition,
+    TemplateExposure,
+    TemplateParameterDefinition,
+    TemplateValue,
+} from './types.js';
+
+export function parseTemplateDefinition(content: string, sourceUri?: string): TemplateDefinition | undefined {
+    const frontMatter = extractLeadingFrontMatter(content);
+    const data = frontMatter?.data;
+    if (!data) {
+        return undefined;
+    }
+    const rawTemplate = data.template;
+    if (!isRecord(rawTemplate)) {
+        return undefined;
+    }
+    const id = normalizeTemplateType(typeof rawTemplate.id === 'string' ? rawTemplate.id : '');
+    if (!id) {
+        return undefined;
+    }
+    const name = typeof rawTemplate.name === 'string' && rawTemplate.name.trim().length > 0
+        ? rawTemplate.name.trim()
+        : undefined;
+    const rank = parseRank(rawTemplate.rank);
+    const exposures = parseTemplateExposures(rawTemplate.expose);
+    const parameters = parseTemplateParameters(rawTemplate.params);
+    return {
+        id,
+        name,
+        rank,
+        exposures,
+        parameters,
+        body: content,
+        sourceUri,
+    };
+}
+
+export function deriveContextLabelFromIri(iri: string): string {
+    const normalized = iri.trim().replace(/^<|>$/g, '');
+    if (!normalized) {
+        return 'IRI';
+    }
+    const hashIndex = normalized.lastIndexOf('#');
+    if (hashIndex >= 0 && hashIndex < normalized.length - 1) {
+        return decodeIriSegment(normalized.slice(hashIndex + 1));
+    }
+    const withoutTrailingSlash = normalized.replace(/\/+$/, '');
+    const slashIndex = withoutTrailingSlash.lastIndexOf('/');
+    if (slashIndex >= 0 && slashIndex < withoutTrailingSlash.length - 1) {
+        return decodeIriSegment(withoutTrailingSlash.slice(slashIndex + 1));
+    }
+    return decodeIriSegment(withoutTrailingSlash);
+}
+
+function normalizeTemplateType(value: string): string {
+    let normalized = value.trim();
+    const wikilinkMatch = /^\[\[([^\]]+)\]\]$/.exec(normalized);
+    if (wikilinkMatch) {
+        normalized = (wikilinkMatch[1] ?? '').trim();
+    }
+    return normalized.replace(/^<|>$/g, '');
+}
+
+function parseTemplateExposures(raw: unknown): TemplateExposure[] {
+    const entries = Array.isArray(raw) ? raw : raw ? [raw] : [];
+    const exposures: TemplateExposure[] = [];
+    for (const entry of entries) {
+        if (!isRecord(entry) || typeof entry.kind !== 'string') {
+            continue;
+        }
+        const kind = entry.kind.trim();
+        if (kind === 'navigation') {
+            const match = isRecord(entry.match) ? entry.match : undefined;
+            const anyTypeOf = asNormalizedStringArray(match?.anyTypeOf);
+            const allTypesOf = asNormalizedStringArray(match?.allTypesOf);
+            exposures.push({
+                kind: 'navigation',
+                match: (anyTypeOf.length > 0 || allTypesOf.length > 0)
+                    ? { anyTypeOf, allTypesOf }
+                    : undefined
+            });
+            continue;
+        }
+        if (kind === 'compose') {
+            const placementRaw = typeof entry.placement === 'string' ? entry.placement.trim() : '';
+            const placement = placementRaw === 'prepend' || placementRaw === 'append' ? placementRaw : undefined;
+            exposures.push({ kind: 'compose', placement });
+            continue;
+        }
+        if (kind === 'call') {
+            const selection = isRecord(entry.selection) ? entry.selection : undefined;
+            const min = toNonNegativeInteger(selection?.min);
+            const max = toNonNegativeInteger(selection?.max);
+            exposures.push({
+                kind: 'call',
+                selection: min !== undefined || max !== undefined ? { min, max } : undefined
+            });
+        }
+    }
+    return exposures;
+}
+
+function parseTemplateParameters(raw: unknown): TemplateParameterDefinition[] {
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    const params: TemplateParameterDefinition[] = [];
+    for (const entry of raw) {
+        if (!isRecord(entry)) {
+            continue;
+        }
+        const id = typeof entry.id === 'string' ? entry.id.trim() : '';
+        const type = typeof entry.type === 'string' ? entry.type.trim() : '';
+        if (!id || !isSupportedParameterType(type)) {
+            continue;
+        }
+        const required = typeof entry.required === 'boolean' ? entry.required : undefined;
+        const fromValue = typeof entry.from === 'string' ? entry.from.trim() : '';
+        const from = isSupportedBindingSource(fromValue) ? fromValue : undefined;
+        const description = typeof entry.description === 'string' && entry.description.trim().length > 0
+            ? entry.description.trim()
+            : undefined;
+        params.push({
+            id,
+            type,
+            required,
+            from,
+            defaultValue: toTemplateValue(entry.defaultValue),
+            description,
+        });
+    }
+    return params;
+}
+
+function isSupportedParameterType(value: string): value is TemplateParameterDefinition['type'] {
+    return value === 'iri'
+        || value === 'string'
+        || value === 'number'
+        || value === 'boolean'
+        || value === 'iri[]'
+        || value === 'json';
+}
+
+function isSupportedBindingSource(value: string): value is NonNullable<TemplateParameterDefinition['from']> {
+    return value === 'context.member'
+        || value === 'context.ontology'
+        || value === 'context.modelUri'
+        || value === 'context.selection[*]'
+        || /^context\.selection\[\d+]$/.test(value)
+        || value === 'user';
+}
+
+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 parseRank(value: unknown): number {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        const parsed = Number(value.trim());
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+    return 0;
+}
+
+function asNormalizedStringArray(value: unknown): string[] {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .filter((entry): entry is string => typeof entry === 'string')
+        .map((entry) => normalizeTemplateType(entry))
+        .filter((entry): entry is string => entry.length > 0);
+}
+
+function toNonNegativeInteger(value: unknown): number | undefined {
+    if (typeof value === 'number' && Number.isInteger(value) && value >= 0) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        const parsed = Number.parseInt(value.trim(), 10);
+        if (Number.isInteger(parsed) && parsed >= 0) {
+            return parsed;
+        }
+    }
+    return undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function decodeIriSegment(value: string): string {
+    if (!value) {
+        return 'IRI';
+    }
+    try {
+        return decodeURIComponent(value);
+    } catch {
+        return value;
+    }
+}

package/src/template/engine.ts

@@ -0,0 +1,45 @@
+// Copyright (c) 2026 Modelware. All rights reserved.
+
+import { bindTemplateParameters } from './binder.js';
+import type { TemplateDefinition, TemplateInvocation, TemplateValue } from './types.js';
+
+export interface TemplateRenderResult {
+    output: string;
+    values: Record<string, TemplateValue>;
+    missingRequired: string[];
+}
+
+export function renderTemplate(
+    template: TemplateDefinition,
+    invocation: TemplateInvocation
+): TemplateRenderResult {
+    const bound = bindTemplateParameters(template, invocation.context, invocation.args);
+    const output = interpolateTemplateBody(template.body, bound.values);
+    return {
+        output,
+        values: bound.values,
+        missingRequired: bound.missingRequired
+    };
+}
+
+export function interpolateTemplateBody(
+    source: string,
+    values: Readonly<Record<string, TemplateValue>>
+): string {
+    return source.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_match: string, key: string): string => {
+        if (!(key in values)) {
+            return '';
+        }
+        const value = values[key];
+        if (Array.isArray(value)) {
+            return value.map((entry) => String(entry)).join(', ');
+        }
+        if (value === null || value === undefined) {
+            return '';
+        }
+        if (typeof value === 'object') {
+            return JSON.stringify(value);
+        }
+        return String(value);
+    });
+}

package/src/template/index.ts

@@ -0,0 +1,9 @@
+// Copyright (c) 2026 Modelware. All rights reserved.
+
+export * from './types.js';
+export * from './catalog.js';
+export * from './resolver.js';
+export * from './binder.js';
+export * from './engine.js';
+export * from './compose.js';
+export * from './definition.js';

package/src/template/resolver.ts

@@ -0,0 +1,75 @@
+// Copyright (c) 2026 Modelware. All rights reserved.
+
+import { getTemplateById, type TemplateCatalog } from './catalog.js';
+import type { TemplateDefinition, TemplateNavigationExposure, TemplateResolutionCandidate, TemplateResolutionResult } from './types.js';
+
+export function resolveTemplateById(catalog: TemplateCatalog, templateId: string): TemplateDefinition | undefined {
+    return getTemplateById(catalog, templateId);
+}
+
+export function resolveTemplateForNavigation(
+    catalog: TemplateCatalog,
+    rdfTypes: ReadonlyArray<string>
+): TemplateResolutionResult {
+    const candidates = collectNavigationCandidates(catalog, rdfTypes);
+    const template = selectBestTemplate(candidates);
+    return { template, candidates };
+}
+
+function collectNavigationCandidates(
+    catalog: TemplateCatalog,
+    rdfTypes: ReadonlyArray<string>
+): TemplateResolutionCandidate[] {
+    const normalizedTypes = [...new Set(rdfTypes.map(normalizeIri).filter((value): value is string => value.length > 0))];
+    const normalizedTypeSet = new Set(normalizedTypes);
+    const results: TemplateResolutionCandidate[] = [];
+    for (const template of catalog.all) {
+        const exposures = template.exposures?.filter((exposure): exposure is TemplateNavigationExposure => exposure.kind === 'navigation') ?? [];
+        if (exposures.length === 0) {
+            continue;
+        }
+        let bestScoreForTemplate: number | undefined;
+        for (const exposure of exposures) {
+            const score = scoreNavigationExposure(exposure, normalizedTypeSet);
+            if (score === undefined) {
+                continue;
+            }
+            if (bestScoreForTemplate === undefined || score > bestScoreForTemplate) {
+                bestScoreForTemplate = score;
+            }
+        }
+        if (bestScoreForTemplate === undefined) {
+            continue;
+        }
+        const rank = Number.isFinite(template.rank) ? Number(template.rank) : 0;
+        results.push({ template, score: bestScoreForTemplate + rank });
+    }
+    return results.sort((left, right) => right.score - left.score || left.template.id.localeCompare(right.template.id));
+}
+
+function scoreNavigationExposure(
+    exposure: TemplateNavigationExposure,
+    rdfTypeSet: ReadonlySet<string>
+): number | undefined {
+    const anyTypeOf = (exposure.match?.anyTypeOf ?? []).map(normalizeIri).filter((value): value is string => value.length > 0);
+    const allTypesOf = (exposure.match?.allTypesOf ?? []).map(normalizeIri).filter((value): value is string => value.length > 0);
+
+    if (allTypesOf.length > 0 && allTypesOf.some((iri) => !rdfTypeSet.has(iri))) {
+        return undefined;
+    }
+    if (anyTypeOf.length > 0 && !anyTypeOf.some((iri) => rdfTypeSet.has(iri))) {
+        return undefined;
+    }
+    if (allTypesOf.length === 0 && anyTypeOf.length === 0) {
+        return 0;
+    }
+    return (allTypesOf.length * 10) + anyTypeOf.length;
+}
+
+function selectBestTemplate(candidates: ReadonlyArray<TemplateResolutionCandidate>): TemplateDefinition | undefined {
+    return candidates.length > 0 ? candidates[0].template : undefined;
+}
+
+function normalizeIri(value: string): string {
+    return value.trim().replace(/^<|>$/g, '');
+}

package/src/template/types.ts

@@ -0,0 +1,111 @@
+// Copyright (c) 2026 Modelware. All rights reserved.
+
+export type TemplateValue = string | number | boolean | null | string[] | Record<string, unknown>;
+
+export type TemplateParameterType =
+    | 'iri'
+    | 'string'
+    | 'number'
+    | 'boolean'
+    | 'iri[]'
+    | 'json';
+
+export type TemplateBindingSource =
+    | 'context.member'
+    | 'context.ontology'
+    | 'context.modelUri'
+    | `context.selection[${number}]`
+    | 'context.selection[*]'
+    | 'user';
+
+export interface TemplateParameterDefinition {
+    id: string;
+    type: TemplateParameterType;
+    required?: boolean;
+    from?: TemplateBindingSource;
+    defaultValue?: TemplateValue;
+    description?: string;
+}
+
+export interface TemplateNavigationMatch {
+    anyTypeOf?: string[];
+    allTypesOf?: string[];
+}
+
+export interface TemplateNavigationExposure {
+    kind: 'navigation';
+    match?: TemplateNavigationMatch;
+}
+
+export interface TemplateComposeExposure {
+    kind: 'compose';
+    placement?: 'prepend' | 'append';
+}
+
+export interface TemplateCallExposure {
+    kind: 'call';
+    selection?: {
+        min?: number;
+        max?: number;
+    };
+}
+
+export type TemplateExposure =
+    | TemplateNavigationExposure
+    | TemplateComposeExposure
+    | TemplateCallExposure;
+
+export interface TemplateDefinition {
+    id: string;
+    name?: string;
+    rank?: number;
+    exposures?: TemplateExposure[];
+    parameters?: TemplateParameterDefinition[];
+    body: string;
+    sourceUri?: string;
+}
+
+export type TemplateInvocationMode = 'navigation' | 'compose' | 'call' | 'preview' | 'inline' | 'newDocument';
+
+export interface TemplateInvocationContext {
+    invocation: {
+        mode: TemplateInvocationMode;
+        sourceDocumentUri?: string;
+        referenceDocumentUri?: string;
+    };
+    model?: {
+        ontologyIri?: string;
+        modelUri?: string;
+    };
+    focus?: {
+        memberIri?: string;
+        rdfTypes?: string[];
+    };
+    selection?: {
+        iris?: string[];
+        rows?: Array<{ iri: string; cells: Record<string, string> }>;
+    };
+    vars?: Record<string, TemplateValue>;
+}
+
+export interface TemplateInvocation {
+    templateId: string;
+    mode: TemplateInvocationMode;
+    context: TemplateInvocationContext;
+    args?: Record<string, TemplateValue>;
+}
+
+export interface TemplateResolutionCandidate {
+    template: TemplateDefinition;
+    score: number;
+}
+
+export interface TemplateResolutionResult {
+    template?: TemplateDefinition;
+    candidates: TemplateResolutionCandidate[];
+}
+
+export interface TemplateBindResult {
+    values: Record<string, TemplateValue>;
+    missingRequired: string[];
+}