structured-render 0.0.0 → 0.0.1

package/dist/render/render-markdown-styles.js

@@ -0,0 +1,242 @@
+import { check } from '@augment-vir/assert';
+import { mapObjectValues, mergeDefinedProperties, } from '@augment-vir/common';
+import { css, CSSResult, unsafeCSS } from 'element-vir';
+import { noNativeSpacing, viraTheme } from 'vira';
+/**
+ * The id attached to the content div which will be rendered to the PDF or image. Use this to create
+ * style selectors.
+ *
+ * @category Internal
+ */
+export const contentDivClass = 'structured-rendering-markdown-rendering-content-for-screenshot';
+/**
+ * Base CSS reset styles that are always applied to the content div, regardless of custom style
+ * overrides. These ensure no unwanted whitespace from default browser margins on the first and last
+ * child elements.
+ *
+ * @category Internal
+ */
+export const baseContentResetStyles = `
+.${contentDivClass} > *:first-child {
+    margin-top: 0;
+}
+.${contentDivClass} > *:last-child {
+    margin-bottom: 0;
+}
+`;
+/**
+ * The standard rendering style configuration.
+ *
+ * @category Internal
+ */
+export const defaultMarkdownStyleConfiguration = {
+    accentColor: 'dodgerblue',
+    bodySize: '14px',
+    h1Size: '32px',
+    h2Size: '24px',
+    h3Size: '18px',
+    h4Size: '16px',
+    h5Size: '14px',
+    h6Size: '14px',
+    bodyGap: '24px',
+    smallTextSize: '10px',
+    liSpacing: '4px',
+    bodyFont: 'sans-serif',
+    codeFont: 'monospace',
+    codeSize: '1em',
+    codeBackgroundColor: viraTheme.colors['vira-grey-behind-fg-small-body'].background.value,
+    /** The selector used that all styles will be applied to. */
+    contentSelector: `.${contentDivClass}`,
+    tableBorderColor: viraTheme.colors['vira-grey-foreground-decoration'].foreground.value,
+    tableBorderWidth: '1px',
+};
+function resolveMarkdownStyleConfiguration(styleOptions) {
+    return mapObjectValues(mergeDefinedProperties(defaultMarkdownStyleConfiguration, styleOptions), (key, value) => {
+        return check.isString(value)
+            ? unsafeCSS(value)
+            : value instanceof CSSResult
+                ? value
+                : value.value;
+    });
+}
+/**
+ * Default plain styles for markdown converted to HTML.
+ *
+ * @category Internal
+ */
+export const defaultMarkdownRenderStyles = configureDefaultMarkdownRenderStyles();
+/**
+ * Configure a stylesheet for rendering.
+ *
+ * @category Internal
+ */
+export function configureDefaultMarkdownRenderStyles(styleOptions) {
+    const styles = resolveMarkdownStyleConfiguration(styleOptions);
+    return css `
+        ${unsafeCSS(styleOptions?.contentSelector || defaultMarkdownStyleConfiguration.contentSelector)} {
+            display: flex;
+            flex-direction: column;
+            gap: ${styles.bodyGap};
+            font-family: ${styles.bodyFont};
+            font-size: ${styles.bodySize};
+            align-items: flex-start;
+
+            & * {
+                font-family: inherit;
+                font-size: inherit;
+                ${noNativeSpacing}
+            }
+
+            & h1 {
+                font-size: ${styles.h1Size};
+            }
+            & h2 {
+                font-size: ${styles.h2Size};
+            }
+            & h3 {
+                font-size: ${styles.h3Size};
+            }
+            & h4 {
+                font-size: ${styles.h4Size};
+            }
+            & h5 {
+                font-size: ${styles.h5Size};
+            }
+            & h6 {
+                font-size: ${styles.h6Size};
+            }
+            & ul,
+            & ol {
+                padding-left: 1.1em;
+                & li {
+                    margin-bottom: ${styles.liSpacing};
+                }
+            }
+            & strong {
+                font-weight: bold;
+            }
+            & em {
+                font-style: italic;
+            }
+            & code {
+                background-color: ${styles.codeBackgroundColor};
+                padding: 2px 6px;
+                border-radius: 4px;
+                font-family: ${styles.codeFont};
+                font-size: ${styles.codeSize};
+            }
+
+            .inlineCode-section {
+                display: inline-flex;
+            }
+
+            & pre {
+                background-color: ${styles.codeBackgroundColor};
+                padding: 2px 12px 6px;
+                border-radius: 6px;
+                white-space: pre-wrap;
+                overflow-x: auto;
+
+                & code {
+                    background-color: transparent;
+                    padding: 0;
+                }
+            }
+
+            & blockquote {
+                border-left: 4px solid ${styles.accentColor};
+                padding-left: 16px;
+                margin-left: 0;
+                font-style: italic;
+            }
+
+            & hr {
+                border: none;
+                border-top: 1px solid currentColor;
+                margin: 20px 0;
+            }
+
+            & small {
+                font-size: ${styles.smallTextSize};
+            }
+
+            & th,
+            & td {
+                border-top: ${styles.tableBorderWidth} solid ${styles.tableBorderColor};
+                border-left: ${styles.tableBorderWidth} solid ${styles.tableBorderColor};
+                padding: 8px 12px;
+                text-align: left;
+            }
+
+            & thead tr:first-child th,
+            & thead tr:first-child td,
+            & tbody tr:first-child th,
+            & tbody tr:first-child td,
+            & tbody tr td.source-cell,
+            & thead tr th.source-cell {
+                border-top-color: transparent;
+            }
+
+            & thead + tbody tr:first-child {
+                & td,
+                & th {
+                    border-top-color: ${styles.tableBorderColor};
+                }
+            }
+
+            & table {
+                border-collapse: collapse;
+                max-width: 100%;
+
+                & th:first-child,
+                & td:first-child {
+                    border-left: none;
+                }
+
+                & th {
+                    font-weight: bold;
+                }
+            }
+
+            & a {
+                color: ${styles.accentColor};
+            }
+
+            & img {
+                max-width: 100%;
+                height: auto;
+            }
+
+            & h1,
+            & h2,
+            & h3,
+            & h4,
+            & h5,
+            & h6 {
+                break-after: avoid;
+                page-break-after: avoid;
+                break-inside: avoid;
+                page-break-inside: avoid;
+            }
+
+            & h2:not(:first-child) {
+                margin-top: 16px;
+            }
+
+            & table,
+            & pre,
+            & blockquote,
+            & ul,
+            & ol,
+            & img {
+                break-inside: avoid;
+                page-break-inside: avoid;
+            }
+
+            & tr {
+                break-inside: avoid;
+                page-break-inside: avoid;
+            }
+        }
+    `;
+}

package/dist/render/render-markdown.d.ts

@@ -0,0 +1,8 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { type RenderInput, type RenderMarkdownOptions } from './render-types.js';
+/**
+ * Convert any structured render data part to markdown.
+ *
+ * @category Render
+ */
+export declare function renderStructuredMarkdown(data: Readonly<RenderInput>, options?: Readonly<PartialWithUndefined<RenderMarkdownOptions>> | undefined): string;

package/dist/render/render-markdown.js

@@ -0,0 +1,169 @@
+import { assert, assertWrap, check } from '@augment-vir/assert';
+import { createArray, filterMap, mergeDefinedProperties, stringify, wrapString, } from '@augment-vir/common';
+import { convertTemplateToString } from 'element-vir';
+import { createStructuredRenderIcon, } from '../structured-render-data/sections/icon.section.js';
+import { StructuredRenderCellDirection, } from '../structured-render-data/sections/table.section.js';
+import { StructuredRenderTextStyle, } from '../structured-render-data/sections/text.section.js';
+import { defaultRenderMarkdownOptions, } from './render-types.js';
+/**
+ * Convert any structured render data part to markdown.
+ *
+ * @category Render
+ */
+export function renderStructuredMarkdown(data, options) {
+    const finalOptions = mergeDefinedProperties(defaultRenderMarkdownOptions, options);
+    return structuredRenderToMarkdownArray(data, finalOptions).filter(check.isTruthy).join('\n\n');
+}
+const markdownStyleWrapper = {
+    [StructuredRenderTextStyle.Bold]: '**',
+};
+function buildVerticalTableRows(section, visibleHeaders, options) {
+    const columnCount = section.entries.length + 1;
+    const dataRows = visibleHeaders.map((header) => {
+        const headerText = header.text
+            ? renderStructuredMarkdown(header.text, options)
+            : header.key;
+        const cells = section.entries.map((entry) => renderStructuredMarkdown(entry.data[header.key], options));
+        return [
+            headerText,
+            ...cells,
+        ];
+    });
+    return [
+        createArray(columnCount, () => ''),
+        ...dataRows,
+    ];
+}
+function buildHorizontalTableRows(section, visibleHeaders, options) {
+    const headerRow = visibleHeaders.map((header) => header.text ? renderStructuredMarkdown(header.text, options) : header.key);
+    const dataRows = section.entries.map((entry) => visibleHeaders.map((header) => renderStructuredMarkdown(entry.data[header.key], options)));
+    return [
+        headerRow,
+        ...dataRows,
+    ];
+}
+const tableRowBuilders = {
+    [StructuredRenderCellDirection.Vertical]: buildVerticalTableRows,
+    [StructuredRenderCellDirection.Horizontal]: buildHorizontalTableRows,
+};
+const markdownRenderers = {
+    icon(section, options) {
+        const coloredIcon = createStructuredRenderIcon(section, options);
+        if (!coloredIcon) {
+            return '';
+        }
+        return convertTemplateToString(coloredIcon.svgTemplate);
+    },
+    codeBlock(section) {
+        return `\`\`\`${section.syntax || ''}\n${section.code}\n\`\`\``;
+    },
+    inlineCode(section) {
+        return `\`${section.code}\``;
+    },
+    empty() {
+        return '';
+    },
+    list(section, options) {
+        return filterMap(section.items, (item) => {
+            const content = renderStructuredMarkdown(item.content, options);
+            const icon = renderStructuredMarkdown(item.icon, options);
+            if (content) {
+                return icon ? `- ${icon} ${content}` : `- ${content}`;
+            }
+            else {
+                return '';
+            }
+        }, check.isTruthy).join('\n');
+    },
+    markdown(section) {
+        return section.markdown;
+    },
+    tag(section) {
+        if (section.text == undefined) {
+            return '';
+        }
+        return String(section.text);
+    },
+    processing() {
+        return '';
+    },
+    source(section, options) {
+        const filteredPageNumbers = section.pageNumbers?.filter(check.isDefined);
+        const pageNumberLine = filteredPageNumbers?.length
+            ? `p. ${filteredPageNumbers.join(', ')}`
+            : '';
+        const pageLine = [
+            section.fileName,
+            pageNumberLine,
+        ]
+            .filter(check.isTruthy)
+            .join(', ');
+        return pageLine ? `<small>${options.sourceString}: ${pageLine}</small>` : '';
+    },
+    table(section, options) {
+        const visibleHeaders = section.headers.filter((header) => !header.hidden);
+        const rows = tableRowBuilders[section.direction](section, visibleHeaders, options);
+        const columnCount = rows[0].length || 0;
+        const colWidths = computeColumnWidths(rows, columnCount);
+        const [headerRow, ...dataRows] = rows;
+        return [
+            formatRow(headerRow, colWidths),
+            formatSeparatorRow(colWidths),
+            ...dataRows.map((row) => formatRow(row, colWidths)),
+        ].join('\n');
+    },
+    text(section, options) {
+        if (section.text == undefined) {
+            return '';
+        }
+        const styleWrapper = (section.style && markdownStyleWrapper[section.style]) || '';
+        const icon = renderStructuredMarkdown(section.icon, options);
+        const text = wrapString({
+            value: String(section.text),
+            wrapper: styleWrapper,
+        });
+        return icon ? `${icon} ${text}` : text;
+    },
+};
+function computeColumnWidths(rows, columnCount) {
+    return createArray(columnCount, (colIndex) => {
+        return rows.reduce((maxWidth, row, rowIndex) => {
+            return Math.max(maxWidth, assertWrap.isDefined(row[colIndex], `No cell at row index ${rowIndex}, column index ${colIndex}`).length);
+        }, 3);
+    });
+}
+function formatRow(cells, widths) {
+    const paddedCells = cells.map((cell, i) => cell.padEnd(widths[i] ?? 3));
+    return `| ${paddedCells.join(' | ')} |`;
+}
+function formatSeparatorRow(widths) {
+    const dashes = widths.map((w) => '-'.repeat(w));
+    return `| ${dashes.join(' | ')} |`;
+}
+function structuredRenderToMarkdownArray(data, options) {
+    if (!data) {
+        return [];
+    }
+    else if (check.isArray(data)) {
+        return data.flatMap((entry) => renderStructuredMarkdown(entry, options));
+    }
+    else if ('type' in data) {
+        const sectionTitle = 'sectionTitle' in data ? data.sectionTitle : undefined;
+        const sources = ('sources' in data && data.sources) || [];
+        return [
+            sectionTitle ? `### ${sectionTitle}` : undefined,
+            markdownRenderers[data.type](data, options),
+            ...sources.map((source) => renderStructuredMarkdown(source, options)),
+        ];
+    }
+    else if ('sections' in data) {
+        return [
+            data.cardTitle && `## ${data.cardTitle}`,
+            ...structuredRenderToMarkdownArray(data.sections, options),
+        ].filter(check.isTruthy);
+    }
+    else {
+        assert.tsType(data).equals();
+        throw new Error(`Unexpected structured render type: ${stringify(data)}`);
+    }
+}

package/dist/render/render-pdf.d.ts

@@ -0,0 +1,35 @@
+import { type PartialWithUndefined } from '@augment-vir/common';
+import { OutputPdfType } from './browser-rendering.js';
+import { type RenderInput, type RenderOptions } from './render-types.js';
+/**
+ * Render to a PDF. Only works in Node.js, not a browser.
+ *
+ * @category Render
+ * @returns The output file path.
+ */
+export declare function renderToNodePdf(renderInput: Readonly<RenderInput>, params: Readonly<{
+    saveLocationPath: string;
+    options?: PartialWithUndefined<RenderOptions> | undefined;
+}>): Promise<string>;
+/**
+ * Render to a PDF. Only works in a browser, not Node.js.
+ *
+ * @category Render
+ */
+export declare function renderToBrowserPdf(renderInput: Readonly<RenderInput>, { pdfOutputType, ...params }: Readonly<{
+    fileName: string;
+} & PartialWithUndefined<{
+    pdfOutputType: OutputPdfType;
+    options: RenderOptions;
+}>>): Promise<unknown>;
+/**
+ * Render to a PDF and trigger the browser's print feature to print that PDF. Only works in a
+ * browser, not Node.js.
+ *
+ * @category Render
+ */
+export declare function printPdf(renderInput: Readonly<RenderInput>, params: Readonly<{
+    fileName: string;
+} & PartialWithUndefined<{
+    options: RenderOptions;
+}>>): Promise<void>;

package/dist/render/render-pdf.js

@@ -0,0 +1,65 @@
+import { isRuntimeEnv, RuntimeEnv } from '@augment-vir/common';
+import { OutputPdfType, renderInBrowser, renderInNode } from './browser-rendering.js';
+/**
+ * Render to a PDF. Only works in Node.js, not a browser.
+ *
+ * @category Render
+ * @returns The output file path.
+ */
+export async function renderToNodePdf(renderInput, params) {
+    if (isRuntimeEnv(RuntimeEnv.Web)) {
+        throw new Error(`${renderToNodePdf.name} cannot run inside of a browser.`);
+    }
+    return await renderInNode(renderInput, {
+        outputType: {
+            pdf: true,
+        },
+        ...params,
+    });
+}
+/**
+ * Render to a PDF. Only works in a browser, not Node.js.
+ *
+ * @category Render
+ */
+export async function renderToBrowserPdf(renderInput, { pdfOutputType, ...params }) {
+    if (!isRuntimeEnv(RuntimeEnv.Web)) {
+        throw new Error(`${renderToBrowserPdf.name} cannot run outside of a browser.`);
+    }
+    return renderInBrowser(renderInput, {
+        outputType: {
+            pdf: pdfOutputType || OutputPdfType.Download,
+        },
+        ...params,
+    });
+}
+/**
+ * Render to a PDF and trigger the browser's print feature to print that PDF. Only works in a
+ * browser, not Node.js.
+ *
+ * @category Render
+ */
+export async function printPdf(renderInput, params) {
+    if (!isRuntimeEnv(RuntimeEnv.Web)) {
+        throw new Error(`${printPdf.name} cannot run outside of a browser.`);
+    }
+    const pdfBlob = (await renderInBrowser(renderInput, {
+        outputType: {
+            pdf: OutputPdfType.Blob,
+        },
+        ...params,
+    }));
+    const blobUrl = URL.createObjectURL(pdfBlob);
+    const printFrame = globalThis.document.createElement('iframe');
+    printFrame.style.display = 'none';
+    printFrame.src = blobUrl;
+    globalThis.document.body.append(printFrame);
+    return new Promise((resolve) => {
+        printFrame.onload = () => {
+            printFrame.contentWindow?.print();
+            URL.revokeObjectURL(blobUrl);
+            resolve();
+            printFrame.remove();
+        };
+    });
+}

package/dist/render/render-types.d.ts

@@ -0,0 +1,134 @@
+import { type MaybeArray } from '@augment-vir/common';
+import { type CSSResult } from 'element-vir';
+import { type ViraIconSvg } from 'vira';
+import { type StructuredRenderCard } from '../structured-render-data/structured-render-card.js';
+import { type StructuredRenderData } from '../structured-render-data/structured-render-data.js';
+import { type StructuredRenderSection } from '../structured-render-data/structured-render-section.js';
+/**
+ * All acceptable inputs for Structured Render rendering.
+ *
+ * @category Internal
+ */
+export type RenderInput = MaybeArray<StructuredRenderData | StructuredRenderCard | StructuredRenderSection | null | undefined>;
+/**
+ * Base options for Structured Render rendering.
+ *
+ * @category Internal
+ */
+export type RenderOptions = Readonly<{
+    /**
+     * Override the default icon set. The default icon set is provided by
+     * [Vira](https://www.npmjs.com/package/vira).
+     */
+    icons: Readonly<{
+        [IconKey in string]: ViraIconSvg;
+    }>;
+    /**
+     * The prefix used when rendering a source.
+     *
+     * @default 'Source'
+     */
+    sourceString: string;
+    /**
+     * The prefix used when rendering multiple sources.
+     *
+     * @default 'Sources'
+     */
+    pluralSourcesString: string;
+}>;
+/**
+ * Default base option values for Structured Render rendering.
+ *
+ * @category Internal
+ */
+export declare const defaultRenderOptions: Readonly<RenderOptions>;
+/**
+ * Option values for Structured Render rendering to Markdown.
+ *
+ * @category Internal
+ */
+export type RenderMarkdownOptions = RenderOptions & {
+    /**
+     * CSS styles for the rendering.
+     *
+     * @default
+     */
+    styles: string | CSSResult;
+};
+/**
+ * Default option values for Structured Render rendering to Markdown.
+ *
+ * @category Internal
+ */
+export declare const defaultRenderMarkdownOptions: Readonly<RenderMarkdownOptions>;
+/**
+ * Option values for Structured Render rendering to HTML.
+ *
+ * @category Internal
+ */
+export type RenderHtmlOptions = RenderOptions & {
+    /** Currently expanded sections and sources. */
+    currentlyExpanded: {
+        [SectionKey in string]: boolean;
+    };
+    /**
+     * The string to use within the processing section.
+     *
+     * @default 'Processing'
+     */
+    processingString: string;
+    /**
+     * The icon shown for source expansion.
+     *
+     * @default DocumentSearch24Icon
+     */
+    sourceIcon: ViraIconSvg;
+    /**
+     * The icon shown next to processing text.
+     *
+     * @default LoaderAnimated24Icon
+     */
+    processingIcon: ViraIconSvg;
+    /**
+     * The icon used for "view on page" buttons.
+     *
+     * @default EyeOpen24Icon
+     */
+    viewOnPageIcon: ViraIconSvg;
+    /**
+     * If `true`, all sources will be expanded when printing.
+     *
+     * @default false
+     */
+    expandSourcesOnPrint: boolean;
+    /**
+     * If `true`, phone-size compatible rendering will be used where supported.
+     *
+     * @default false
+     */
+    isPhoneSize: boolean;
+    /**
+     * If `true`, the view-on-page eyeball buttons are not rendered.
+     *
+     * @default false
+     */
+    hideViewOnPageButtons: boolean;
+    /**
+     * Create a string for the source "view on page" buttons.
+     *
+     * This will only be used if `hideViewOnPageButtons` is not set to `true`.
+     */
+    createViewOnPageString(pageNumber: number): string;
+    /**
+     * CSS styles for rendering internal Markdown.
+     *
+     * @default
+     */
+    markdownStyles: string | CSSResult;
+};
+/**
+ * Default option values for Structured Render rendering to HTML.
+ *
+ * @category Internal
+ */
+export declare const defaultRenderHtmlOptions: Readonly<RenderHtmlOptions>;

package/dist/render/render-types.js

@@ -0,0 +1,41 @@
+import { allIconsByName, DocumentSearch24Icon, EyeOpen24Icon, LoaderAnimated24Icon, } from 'vira';
+import { defaultMarkdownRenderStyles } from './render-markdown-styles.js';
+/**
+ * Default base option values for Structured Render rendering.
+ *
+ * @category Internal
+ */
+export const defaultRenderOptions = {
+    icons: allIconsByName,
+    sourceString: 'Source',
+    pluralSourcesString: 'Sources',
+};
+/**
+ * Default option values for Structured Render rendering to Markdown.
+ *
+ * @category Internal
+ */
+export const defaultRenderMarkdownOptions = {
+    ...defaultRenderOptions,
+    styles: defaultMarkdownRenderStyles,
+};
+/**
+ * Default option values for Structured Render rendering to HTML.
+ *
+ * @category Internal
+ */
+export const defaultRenderHtmlOptions = {
+    ...defaultRenderOptions,
+    processingString: 'Processing',
+    currentlyExpanded: {},
+    sourceIcon: DocumentSearch24Icon,
+    viewOnPageIcon: EyeOpen24Icon,
+    processingIcon: LoaderAnimated24Icon,
+    expandSourcesOnPrint: false,
+    hideViewOnPageButtons: false,
+    isPhoneSize: false,
+    markdownStyles: defaultMarkdownRenderStyles,
+    createViewOnPageString(pageNumber) {
+        return `View on page ${pageNumber}`;
+    },
+};