mviz 1.6.4 → 1.6.7

package/dist/layout/block-loader.js

@@ -0,0 +1,143 @@
+/**
+ * Phase 2: Load + convert + validate.
+ *
+ * Walks a raw IR (from markdown-parser) and resolves every `RawCodeBlockItem`
+ * into a `ParsedItem` by:
+ *   - reading any `file=` reference (CSV or JSON)
+ *   - parsing inline JSON
+ *   - merging file data with inline options
+ *   - applying columnar -> standard format conversion
+ *   - injecting frontmatter currency / theme defaults
+ *   - linting the resulting spec
+ *
+ * Errors collected during this phase are returned as a string list so the
+ * caller can report them in non-strict mode or short-circuit in strict mode.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { lintSpec } from '../core/linter.js';
+import { convertColumnarFormat } from './converter.js';
+import { parseCsv } from './csv.js';
+/**
+ * Resolve all raw items into parsed items. Walks every section/row/item.
+ */
+export function loadSections(rawSections, options) {
+    const errors = [];
+    const sections = rawSections.map((raw) => loadSection(raw, options, errors));
+    return { sections, errors };
+}
+function loadSection(raw, options, errors) {
+    const rows = [];
+    for (const rawRow of raw.rows) {
+        const row = loadRow(rawRow, options, errors);
+        if (row.length > 0)
+            rows.push(row);
+    }
+    const section = { title: raw.title, rows };
+    if (raw.pageBreak !== undefined)
+        section.pageBreak = raw.pageBreak;
+    if (raw.hasDivider !== undefined)
+        section.hasDivider = raw.hasDivider;
+    return section;
+}
+function loadRow(rawRow, options, errors) {
+    const out = [];
+    for (const raw of rawRow) {
+        if (raw.kind === 'resolved') {
+            out.push(raw.item);
+            continue;
+        }
+        const item = loadCodeBlock(raw, options, errors);
+        if (item)
+            out.push(item);
+    }
+    return out;
+}
+/**
+ * Resolve a single code block into a ParsedItem (or null on non-fatal failure).
+ */
+function loadCodeBlock(raw, options, errors) {
+    try {
+        const spec = buildSpec(raw, options);
+        if (spec === null)
+            return null;
+        lintSpec({ ...spec, type: raw.type }, options.lintMode);
+        const item = { type: raw.type, spec };
+        if (raw.size)
+            item.size = raw.size;
+        return item;
+    }
+    catch (e) {
+        const errorMsg = e instanceof Error ? e.message : 'Unknown error';
+        const formatted = `Line ${raw.startLine}, \`\`\`${raw.type}: ${errorMsg}`;
+        errors.push(formatted);
+        if (options.strict)
+            throw new Error(formatted);
+        return null;
+    }
+}
+/**
+ * Build the final spec for a code block by merging any file data with the
+ * inline JSON, applying defaults, and running columnar conversion.
+ *
+ * Returns null when the block is empty (no inline JSON, no file).
+ */
+function buildSpec(raw, options) {
+    const fileResult = loadFileData(raw.file, options);
+    let spec = fileResult.spec;
+    const fileData = fileResult.data;
+    if (raw.inlineLines.length > 0) {
+        const inlineSpec = JSON.parse(raw.inlineLines.join('\n'));
+        spec = fileData !== null ? { ...inlineSpec, data: fileData } : inlineSpec;
+    }
+    else if (fileData !== null) {
+        spec = autoDetectFromCsv(fileData);
+    }
+    if (!spec.data && Object.keys(spec).length === 0)
+        return null;
+    spec = convertColumnarFormat(spec);
+    applySpecDefaults(spec, options.frontmatter);
+    return spec;
+}
+function loadFileData(file, options) {
+    const empty = { data: null, spec: {} };
+    if (!file || !options.baseDir)
+        return empty;
+    const filePath = resolve(options.baseDir, file);
+    if (!existsSync(filePath)) {
+        if (options.strict)
+            throw new Error(`File not found: ${filePath}`);
+        return empty;
+    }
+    if (file.endsWith('.csv')) {
+        return { data: parseCsv(filePath), spec: {} };
+    }
+    if (file.endsWith('.json')) {
+        return loadJsonFile(filePath);
+    }
+    return empty;
+}
+function loadJsonFile(filePath) {
+    const content = readFileSync(filePath, 'utf-8');
+    const parsed = JSON.parse(content);
+    if (Array.isArray(parsed)) {
+        return { data: parsed, spec: {} };
+    }
+    return { data: null, spec: convertColumnarFormat(parsed) };
+}
+function autoDetectFromCsv(fileData) {
+    const spec = { data: fileData };
+    const columns = fileData.length > 0 ? Object.keys(fileData[0]) : [];
+    if (columns.length >= 2) {
+        spec.x = columns[0];
+        spec.y = columns[1];
+    }
+    return spec;
+}
+function applySpecDefaults(spec, frontmatter) {
+    spec.theme = (spec.theme ?? frontmatter.theme);
+    if (!spec.currency && frontmatter.currency) {
+        spec.currency = frontmatter.currency;
+    }
+}
+//# sourceMappingURL=block-loader.js.map

package/dist/layout/layout-resolver.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Phase 3: Layout resolution.
+ *
+ * Resolves auto-sized items in each row to concrete `[cols, rows]` sizes and
+ * validates print mode (which requires every component to have an explicit
+ * size). Operates in-place on the resolved `Section[]` IR.
+ */
+import type { ParsedItem, Section } from './parser-types.js';
+export interface LayoutOptions {
+    printMode: boolean;
+    strict: boolean;
+}
+export interface LayoutResult {
+    errors: string[];
+}
+/**
+ * Validate print mode (if enabled) and then resolve auto sizes.
+ *
+ * IMPORTANT — order matters:
+ *   1. Print-mode validation runs FIRST against the original sizing intent so
+ *      `size=auto` (and missing sizes) are still visible as `'auto' | null`
+ *      sentinels. The pre-refactor parser ran in this order; flipping it
+ *      causes `print: true` + `size=auto` specs to silently pass because
+ *      `auto` markers are replaced with concrete `[cols, rows]` numbers.
+ *   2. Auto-size resolution happens AFTER, mutating items in place.
+ */
+export declare function resolveLayout(sections: Section[], options: LayoutOptions): LayoutResult;
+/**
+ * Resolve `auto` sizes in a single row by distributing remaining grid columns
+ * across the auto-sized items.
+ */
+export declare function resolveAutoSizes(row: ParsedItem[]): void;
+//# sourceMappingURL=layout-resolver.d.ts.map

package/dist/layout/layout-resolver.js

@@ -0,0 +1,73 @@
+/**
+ * Phase 3: Layout resolution.
+ *
+ * Resolves auto-sized items in each row to concrete `[cols, rows]` sizes and
+ * validates print mode (which requires every component to have an explicit
+ * size). Operates in-place on the resolved `Section[]` IR.
+ */
+import { DEFAULT_SIZES, GRID_TOTAL_COLUMNS, autoSizeChart } from '../core/themes.js';
+/** Minimum column span granted to an `auto`-sized item. */
+const MIN_AUTO_COLUMN_SPAN = 4;
+/**
+ * Validate print mode (if enabled) and then resolve auto sizes.
+ *
+ * IMPORTANT — order matters:
+ *   1. Print-mode validation runs FIRST against the original sizing intent so
+ *      `size=auto` (and missing sizes) are still visible as `'auto' | null`
+ *      sentinels. The pre-refactor parser ran in this order; flipping it
+ *      causes `print: true` + `size=auto` specs to silently pass because
+ *      `auto` markers are replaced with concrete `[cols, rows]` numbers.
+ *   2. Auto-size resolution happens AFTER, mutating items in place.
+ */
+export function resolveLayout(sections, options) {
+    const errors = [];
+    if (options.printMode) {
+        validatePrintMode(sections, options.strict, errors);
+    }
+    for (const section of sections) {
+        for (const row of section.rows) {
+            resolveAutoSizes(row);
+        }
+    }
+    return { errors };
+}
+/**
+ * Resolve `auto` sizes in a single row by distributing remaining grid columns
+ * across the auto-sized items.
+ */
+export function resolveAutoSizes(row) {
+    const autoItems = [];
+    let fixedCols = 0;
+    for (const item of row) {
+        if (item.size === 'auto') {
+            autoItems.push(item);
+        }
+        else {
+            const size = item.size ?? DEFAULT_SIZES[item.type] ?? [8, 4];
+            fixedCols += size[0];
+        }
+    }
+    if (autoItems.length === 0)
+        return;
+    const remainingCols = Math.max(0, GRID_TOTAL_COLUMNS - fixedCols);
+    const colsPerAuto = Math.max(MIN_AUTO_COLUMN_SPAN, Math.floor(remainingCols / autoItems.length));
+    for (const item of autoItems) {
+        const [autoCols, autoRows] = autoSizeChart(item.type, item.spec);
+        item.size = autoItems.length === 1 ? [autoCols, autoRows] : [Math.min(autoCols, colsPerAuto), autoRows];
+    }
+}
+function validatePrintMode(sections, strict, errors) {
+    for (const section of sections) {
+        for (const row of section.rows) {
+            for (const item of row) {
+                if (item.size === null || item.size === undefined || item.size === 'auto') {
+                    const msg = `Print mode requires explicit size for "${item.type}" component. Use size=[cols,rows] syntax.`;
+                    if (strict)
+                        throw new Error(msg);
+                    errors.push(msg);
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=layout-resolver.js.map

package/dist/layout/markdown-parser.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Phase 1: Markdown -> raw IR.
+ *
+ * Pure tokenization. Reads a markdown string and produces a `ParsedMarkdown`
+ * IR consisting of sections, rows, and items. Code blocks are emitted as
+ * `RawCodeBlockItem`s with their inline body still as raw text — no file I/O,
+ * no JSON parsing, no validation happens here.
+ *
+ * Frontmatter parsing also lives in this module (see `parseFrontmatter`).
+ */
+import type { ParsedFrontmatter, ParsedItem, ParsedMarkdown } from './parser-types.js';
+/**
+ * Parse YAML-like frontmatter from the head of a markdown document.
+ */
+export declare function parseFrontmatter(lines: string[], baseTheme: string): ParsedFrontmatter;
+/**
+ * Parse a code-block opening line (everything after the leading ```), extracting
+ * type, optional `size=` directive, and optional `file=` reference.
+ */
+export declare function parseCodeBlockHeader(headerLine: string): {
+    type: string;
+    size: [number, number] | 'auto' | null;
+    file: string | null;
+};
+/**
+ * Parse a markdown table block (lines starting with `|`) into a table item.
+ * Returns null if the block isn't a valid table.
+ */
+export declare function parseMarkdownTable(tableLines: string[], theme: string): ParsedItem | null;
+/**
+ * Parse markdown into a raw IR.
+ */
+export declare function parseMarkdown(markdown: string, baseTheme: string): ParsedMarkdown;
+//# sourceMappingURL=markdown-parser.d.ts.map

package/dist/layout/markdown-parser.js

@@ -0,0 +1,395 @@
+/**
+ * Phase 1: Markdown -> raw IR.
+ *
+ * Pure tokenization. Reads a markdown string and produces a `ParsedMarkdown`
+ * IR consisting of sections, rows, and items. Code blocks are emitted as
+ * `RawCodeBlockItem`s with their inline body still as raw text — no file I/O,
+ * no JSON parsing, no validation happens here.
+ *
+ * Frontmatter parsing also lives in this module (see `parseFrontmatter`).
+ */
+/**
+ * Parse YAML-like frontmatter from the head of a markdown document.
+ */
+export function parseFrontmatter(lines, baseTheme) {
+    const initial = createDefaultFrontmatter(lines, baseTheme);
+    if (lines.length === 0 || lines[0] !== '---')
+        return initial;
+    const frontmatterEnd = findFrontmatterEnd(lines);
+    if (frontmatterEnd <= 0)
+        return initial;
+    const result = { ...initial };
+    for (let i = 1; i < frontmatterEnd; i++) {
+        applyFrontmatterLine(result, lines[i]);
+    }
+    result.remainingLines = lines.slice(frontmatterEnd + 1);
+    result.frontmatterEndLine = frontmatterEnd + 1;
+    return result;
+}
+function createDefaultFrontmatter(lines, baseTheme) {
+    return {
+        theme: baseTheme,
+        pageTitle: 'Dashboard',
+        pageTitleFromFrontmatter: false,
+        continuous: false,
+        orientation: 'portrait',
+        printMode: false,
+        currency: undefined,
+        remainingLines: lines,
+        frontmatterEndLine: 0,
+    };
+}
+function findFrontmatterEnd(lines) {
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i] === '---')
+            return i;
+    }
+    return -1;
+}
+function applyFrontmatterLine(target, line) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx <= 0)
+        return;
+    const key = line.slice(0, colonIdx).trim();
+    let val = line.slice(colonIdx + 1).trim();
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+        val = val.slice(1, -1);
+    }
+    if (key === 'theme')
+        target.theme = val;
+    else if (key === 'title') {
+        target.pageTitle = val;
+        target.pageTitleFromFrontmatter = true;
+    }
+    else if (key === 'continuous')
+        target.continuous = isTruthy(val);
+    else if (key === 'orientation' && (val === 'landscape' || val === 'portrait')) {
+        target.orientation = val;
+    }
+    else if (key === 'print')
+        target.printMode = isTruthy(val);
+    else if (key === 'currency')
+        target.currency = val.toUpperCase();
+}
+function isTruthy(val) {
+    return ['true', 'yes', '1'].includes(val.toLowerCase());
+}
+/**
+ * Parse a code-block opening line (everything after the leading ```), extracting
+ * type, optional `size=` directive, and optional `file=` reference.
+ */
+export function parseCodeBlockHeader(headerLine) {
+    let header = headerLine.slice(3).trim();
+    let size = null;
+    if (/size\s*=\s*auto\b/.test(header)) {
+        size = 'auto';
+        header = header.replace(/\s*size\s*=\s*auto\b/, '');
+    }
+    else {
+        const m = header.match(/size\s*=\s*\[\s*(\d+)\s*,\s*(\d+)\s*\]/);
+        if (m) {
+            size = [parseInt(m[1], 10), parseInt(m[2], 10)];
+            header = header.replace(/\s*size\s*=\s*\[\s*\d+\s*,\s*\d+\s*\]/, '');
+        }
+    }
+    let file = null;
+    if (header.includes(' file=')) {
+        const parts = header.split(' file=');
+        header = parts[0].trim();
+        file = parts[1]?.trim() ?? null;
+    }
+    const type = header.split(' ')[0] ?? '';
+    return { type, size, file };
+}
+/**
+ * Parse a markdown table block (lines starting with `|`) into a table item.
+ * Returns null if the block isn't a valid table.
+ */
+export function parseMarkdownTable(tableLines, theme) {
+    if (tableLines.length < 2)
+        return null;
+    const headers = parseTableHeaders(tableLines[0]);
+    if (!headers || headers.length === 0)
+        return null;
+    const alignments = parseTableAlignments(tableLines[1], headers.length);
+    if (!alignments)
+        return null;
+    const data = parseTableRows(tableLines.slice(2), headers);
+    if (data.length === 0)
+        return null;
+    const columns = headers.map((header, i) => ({
+        id: header,
+        title: header,
+        align: alignments[i] ?? 'left',
+    }));
+    return { type: 'table', spec: { data, columns, theme } };
+}
+function parseTableHeaders(line) {
+    let trimmed = line.trim();
+    if (!trimmed.startsWith('|') || !trimmed.endsWith('|')) {
+        trimmed = '|' + trimmed + '|';
+    }
+    return trimmed.split('|').slice(1, -1).map((h) => h.trim());
+}
+function parseTableAlignments(sepLine, headerCount) {
+    const trimmed = sepLine.trim();
+    if (!trimmed.includes('-'))
+        return null;
+    const parts = trimmed.split('|').slice(1, -1).map((s) => s.trim());
+    const alignments = parts.map((part) => {
+        if (part.startsWith(':') && part.endsWith(':'))
+            return 'center';
+        if (part.endsWith(':'))
+            return 'right';
+        return 'left';
+    });
+    while (alignments.length < headerCount)
+        alignments.push('left');
+    return alignments;
+}
+function parseTableRows(lines, headers) {
+    const data = [];
+    for (const raw of lines) {
+        let line = raw.trim();
+        if (!line || line.startsWith('|---') || /^[|\-:\s]+$/.test(line))
+            continue;
+        if (!line.startsWith('|'))
+            line = '|' + line + '|';
+        const cells = line.split('|').slice(1, -1).map((c) => c.trim());
+        if (cells.length === 0)
+            continue;
+        const row = {};
+        for (let j = 0; j < headers.length; j++) {
+            row[headers[j]] = coerceCellValue(cells[j] ?? '');
+        }
+        data.push(row);
+    }
+    return data;
+}
+function coerceCellValue(value) {
+    if (value === '')
+        return value;
+    if (value.includes('.')) {
+        const num = parseFloat(value);
+        if (!isNaN(num))
+            return num;
+    }
+    else {
+        const num = parseInt(value, 10);
+        if (!isNaN(num))
+            return num;
+    }
+    return value;
+}
+/**
+ * Parse markdown into a raw IR.
+ */
+export function parseMarkdown(markdown, baseTheme) {
+    const lines = markdown.trim().split('\n');
+    const frontmatter = parseFrontmatter(lines, baseTheme);
+    const state = createParseState(frontmatter);
+    for (let i = 0; i < frontmatter.remainingLines.length; i++) {
+        processLine(state, frontmatter.remainingLines[i], frontmatter.frontmatterEndLine + i + 1);
+    }
+    finalizeParseState(state);
+    return { frontmatter, sections: state.sections, pageTitle: state.pageTitle };
+}
+function createParseState(frontmatter) {
+    return {
+        theme: frontmatter.theme,
+        sections: [],
+        currentSection: { title: '', rows: [] },
+        currentRow: [],
+        inCodeBlock: false,
+        codeType: '',
+        codeContent: [],
+        codeSize: null,
+        codeFile: null,
+        codeStartLine: 0,
+        paragraphLines: [],
+        inMarkdownTable: false,
+        markdownTableLines: [],
+        handledFirstH1: false,
+        pageTitle: frontmatter.pageTitle,
+        pageTitleFromFrontmatter: frontmatter.pageTitleFromFrontmatter,
+    };
+}
+function flushParagraph(s) {
+    if (s.paragraphLines.length === 0)
+        return;
+    const text = s.paragraphLines.join(' ').trim();
+    if (text) {
+        pushResolvedItem(s.currentRow, { type: 'text', spec: { content: text, theme: s.theme } });
+    }
+    s.paragraphLines = [];
+}
+function flushMarkdownTable(s) {
+    if (s.markdownTableLines.length > 0) {
+        const tableItem = parseMarkdownTable(s.markdownTableLines, s.theme);
+        if (tableItem)
+            pushResolvedItem(s.currentRow, tableItem);
+        s.markdownTableLines = [];
+    }
+    s.inMarkdownTable = false;
+}
+function flushRow(s) {
+    if (s.currentRow.length > 0) {
+        s.currentSection.rows.push(s.currentRow);
+        s.currentRow = [];
+    }
+}
+function pushResolvedItem(row, item) {
+    const wrapped = { kind: 'resolved', item };
+    row.push(wrapped);
+}
+function startSection(s, next) {
+    if (s.currentSection.rows.length > 0 || s.currentSection.title) {
+        s.sections.push(s.currentSection);
+    }
+    s.currentSection = next;
+}
+function processLine(s, line, _absoluteLineNum) {
+    if (line.startsWith('```')) {
+        handleFence(s, line, _absoluteLineNum);
+        return;
+    }
+    if (s.inCodeBlock) {
+        s.codeContent.push(line);
+        return;
+    }
+    if (handleHeading(s, line))
+        return;
+    if (handlePageOrDivider(s, line))
+        return;
+    if (!line.trim()) {
+        flushParagraph(s);
+        if (s.inMarkdownTable)
+            flushMarkdownTable(s);
+        if (s.currentRow.length > 0)
+            flushRow(s);
+        return;
+    }
+    if (line.trim().startsWith('|')) {
+        flushParagraph(s);
+        s.inMarkdownTable = true;
+        s.markdownTableLines.push(line);
+        return;
+    }
+    if (s.inMarkdownTable)
+        flushMarkdownTable(s);
+    s.paragraphLines.push(line);
+}
+function handleFence(s, line, absoluteLineNum) {
+    if (!s.inCodeBlock) {
+        flushParagraph(s);
+        const { type, size, file } = parseCodeBlockHeader(line);
+        s.codeType = type;
+        s.codeSize = size;
+        s.codeFile = file;
+        s.codeContent = [];
+        s.codeStartLine = absoluteLineNum;
+        s.inCodeBlock = true;
+        return;
+    }
+    s.inCodeBlock = false;
+    if (s.codeType) {
+        const block = {
+            kind: 'code',
+            type: s.codeType,
+            inlineLines: s.codeContent,
+            file: s.codeFile,
+            size: s.codeSize,
+            startLine: s.codeStartLine,
+        };
+        s.currentRow.push(block);
+    }
+    s.codeType = '';
+    s.codeContent = [];
+    s.codeSize = null;
+    s.codeFile = null;
+}
+function handleHeading(s, line) {
+    if (line.startsWith('# ') && !line.startsWith('## ') && !line.startsWith('### ')) {
+        handleH1(s, line.slice(2).trim());
+        return true;
+    }
+    if (line.startsWith('## ') && !line.startsWith('### ')) {
+        flushParagraph(s);
+        flushRow(s);
+        startSection(s, { title: line.slice(3).trim(), rows: [] });
+        return true;
+    }
+    if (line.startsWith('### ')) {
+        flushParagraph(s);
+        if (s.inMarkdownTable)
+            flushMarkdownTable(s);
+        flushRow(s);
+        pushResolvedItem(s.currentRow, {
+            type: 'inline_header',
+            spec: { text: line.slice(4).trim(), theme: s.theme },
+        });
+        flushRow(s);
+        return true;
+    }
+    return false;
+}
+/**
+ * Handle a leading or non-leading H1.
+ *
+ * Leading H1 disambiguation (issue #249):
+ *   1. No frontmatter title: leading H1 becomes the page title (no section).
+ *   2. Frontmatter title matches H1: suppress the H1 (no section).
+ *   3. Frontmatter + different H1: render H1 as a section (legacy behavior).
+ * Non-leading H1s always render as a section.
+ */
+function handleH1(s, headingText) {
+    flushParagraph(s);
+    flushRow(s);
+    const isLeading = !s.handledFirstH1 &&
+        s.sections.length === 0 &&
+        s.currentSection.rows.length === 0 &&
+        !s.currentSection.title;
+    if (isLeading) {
+        s.handledFirstH1 = true;
+        if (!s.pageTitleFromFrontmatter) {
+            // Case 1: promote leading H1 to page title.
+            s.pageTitle = headingText;
+            return;
+        }
+        if (s.pageTitle.trim().toLowerCase() === headingText.toLowerCase()) {
+            // Case 2: H1 duplicates frontmatter title — suppress.
+            return;
+        }
+        // Case 3: fall through to legacy section behavior.
+    }
+    startSection(s, { title: headingText, rows: [] });
+}
+function handlePageOrDivider(s, line) {
+    if (line.trim() === '===') {
+        flushParagraph(s);
+        if (s.inMarkdownTable)
+            flushMarkdownTable(s);
+        flushRow(s);
+        startSection(s, { title: '', rows: [], pageBreak: true });
+        return true;
+    }
+    if (['---', '***', '___'].includes(line.trim())) {
+        flushParagraph(s);
+        if (s.inMarkdownTable)
+            flushMarkdownTable(s);
+        flushRow(s);
+        startSection(s, { title: '', rows: [], hasDivider: true });
+        return true;
+    }
+    return false;
+}
+function finalizeParseState(s) {
+    flushParagraph(s);
+    if (s.inMarkdownTable)
+        flushMarkdownTable(s);
+    flushRow(s);
+    if (s.currentSection.rows.length > 0 || s.currentSection.title) {
+        s.sections.push(s.currentSection);
+    }
+}
+//# sourceMappingURL=markdown-parser.js.map