orz-paged 0.1.0

package/dist/doc/fonts.js

@@ -0,0 +1,83 @@
+/**
+ * Font presets — M3.
+ *
+ * Maps each curated {@link FontPresetName} to a {@link FontPreset}: a CDN
+ * stylesheet URL (`@fontsource/*` served via jsDelivr) plus the matching CSS
+ * `font-family` stack. orz-paged assumes internet access, so fonts load from
+ * the CDN rather than being bundled.
+ *
+ * `system-serif` is the one preset with **no** webfont — it relies on the
+ * platform's Times-style serif and ships an empty `cssUrl`.
+ *
+ * Source of truth for the curated list: `docs/document-model.md` (Tier A) and
+ * `src/types.ts` (`FontPresetName`).
+ */
+/** jsDelivr `@fontsource` stylesheet for a given package id (major v5). */
+function fontsourceUrl(id) {
+    return `https://cdn.jsdelivr.net/npm/@fontsource/${id}@5/index.css`;
+}
+/** Times-style fallback stack for the webfont-less `system-serif` preset. */
+const SYSTEM_SERIF_FAMILY = '"Times New Roman", Times, Georgia, "Liberation Serif", serif';
+/**
+ * Every curated preset → its CDN stylesheet + CSS family stack. `system-serif`
+ * carries an empty `cssUrl` (no network font).
+ */
+export const FONT_PRESETS = {
+    'system-serif': {
+        cssUrl: '',
+        family: SYSTEM_SERIF_FAMILY,
+    },
+    'source-serif-4': {
+        cssUrl: fontsourceUrl('source-serif-4'),
+        family: '"Source Serif 4", Georgia, "Times New Roman", serif',
+    },
+    lora: {
+        cssUrl: fontsourceUrl('lora'),
+        family: '"Lora", Georgia, "Times New Roman", serif',
+    },
+    'crimson-pro': {
+        cssUrl: fontsourceUrl('crimson-pro'),
+        family: '"Crimson Pro", Georgia, "Times New Roman", serif',
+    },
+    'noto-serif': {
+        cssUrl: fontsourceUrl('noto-serif'),
+        family: '"Noto Serif", Georgia, "Times New Roman", serif',
+    },
+    inter: {
+        cssUrl: fontsourceUrl('inter'),
+        family: '"Inter", "Helvetica Neue", Helvetica, Arial, sans-serif',
+    },
+    'ibm-plex-sans': {
+        cssUrl: fontsourceUrl('ibm-plex-sans'),
+        family: '"IBM Plex Sans", "Helvetica Neue", Helvetica, Arial, sans-serif',
+    },
+    roboto: {
+        cssUrl: fontsourceUrl('roboto'),
+        family: '"Roboto", "Helvetica Neue", Helvetica, Arial, sans-serif',
+    },
+    raleway: {
+        cssUrl: fontsourceUrl('raleway'),
+        family: '"Raleway", "Helvetica Neue", Helvetica, Arial, sans-serif',
+    },
+    'noto-sans': {
+        cssUrl: fontsourceUrl('noto-sans'),
+        family: '"Noto Sans", "Helvetica Neue", Helvetica, Arial, sans-serif',
+    },
+    'courier-prime': {
+        cssUrl: fontsourceUrl('courier-prime'),
+        family: '"Courier Prime", "Courier New", Courier, monospace',
+    },
+};
+/** Sensible fallback for an unknown preset name: the webfont-less system serif. */
+const SYSTEM_FALLBACK = {
+    cssUrl: '',
+    family: SYSTEM_SERIF_FAMILY,
+};
+/**
+ * Resolve a preset by name. Unknown names fall back to a webfont-less system
+ * serif (empty `cssUrl`) rather than throwing.
+ */
+export function fontPreset(name) {
+    const preset = FONT_PRESETS[name];
+    return preset ?? SYSTEM_FALLBACK;
+}

package/dist/doc/nyml.js

@@ -0,0 +1,140 @@
+/**
+ * Generic nyml-block scanner — shared by the settings reader (M1) and the
+ * assembler (A1).
+ *
+ * `settings.ts` parses the single `kind: document` block inline; this module is
+ * the reusable version: it finds **every** `{{nyml … }}` block in a source,
+ * parses its YAML-ish `key: value` body (including `key: |` multiline blocks),
+ * reads the `kind:` discriminator, and reports the block's char offsets so a
+ * caller can splice it out / replace it.
+ *
+ * Values are always strings: surrounding quotes are stripped, multiline `|`
+ * blocks are dedented and joined with `\n`. The `{{nyml … }}` grammar matches
+ * what `parseDocSettings` already accepts (`}` is allowed inside the body; only
+ * the first `}}` terminates the block).
+ */
+const OPEN = '{{nyml';
+/** Find the index of the `}}` that closes a `{{nyml` opened at/after `from`. */
+function findClosing(source, from) {
+    for (let i = from; i < source.length - 1; i++) {
+        if (source[i] === '}' && source[i + 1] === '}')
+            return i;
+    }
+    return -1;
+}
+/** Strip a single pair of matching surrounding quotes, if present. */
+function stripQuotes(s) {
+    if (s.length >= 2) {
+        const first = s[0];
+        const last = s[s.length - 1];
+        if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+            return s.slice(1, -1);
+        }
+    }
+    return s;
+}
+/**
+ * Parse a nyml body into a flat `key: value` map plus its `kind`. Supports
+ * `key: |` multiline blocks: subsequent lines indented more than the key are
+ * dedented (block style) and joined with `\n`. The `kind:` line populates
+ * `kind` rather than `fields`.
+ */
+function parseBody(inner) {
+    const fields = {};
+    let kind = '';
+    const lines = inner.split('\n');
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        const m = /^(\s*)([A-Za-z0-9_]+)\s*:\s?(.*)$/.exec(line);
+        if (!m) {
+            i++;
+            continue;
+        }
+        const indent = m[1].length;
+        const key = m[2];
+        const value = m[3];
+        if (value.trim() === '|') {
+            // Multiline block: gather following lines indented more than this key.
+            const collected = [];
+            let blockIndent = -1;
+            i++;
+            while (i < lines.length) {
+                const next = lines[i];
+                if (next.trim() === '') {
+                    collected.push('');
+                    i++;
+                    continue;
+                }
+                const nextIndent = next.match(/^[ \t]*/)?.[0].length ?? 0;
+                if (nextIndent <= indent)
+                    break;
+                if (blockIndent === -1)
+                    blockIndent = nextIndent;
+                collected.push(next.slice(Math.min(blockIndent, nextIndent)));
+                i++;
+            }
+            while (collected.length && collected[collected.length - 1] === '') {
+                collected.pop();
+            }
+            const joined = collected.join('\n');
+            if (key === 'kind')
+                kind = joined.trim();
+            else
+                fields[key] = joined;
+            continue;
+        }
+        const v = stripQuotes(value.trim());
+        if (key === 'kind')
+            kind = v;
+        else
+            fields[key] = v;
+        i++;
+    }
+    return { kind, fields };
+}
+/** Char ranges `[start, end)` covered by HTML comments `<!-- … -->`. */
+function commentRanges(source) {
+    const ranges = [];
+    let i = 0;
+    while (true) {
+        const open = source.indexOf('<!--', i);
+        if (open === -1)
+            break;
+        const close = source.indexOf('-->', open + 4);
+        if (close === -1) {
+            ranges.push([open, source.length]);
+            break;
+        } // unclosed → to end
+        ranges.push([open, close + 3]);
+        i = close + 3;
+    }
+    return ranges;
+}
+/**
+ * Scan a source for every `{{nyml … }}` block, in document order. Each result
+ * carries its parsed `kind`, `fields`, and `[start, end)` char offsets. Blocks
+ * inside an HTML comment (`<!-- … -->`) are skipped — so a commented-out element
+ * (e.g. content the editor's template picker preserves) does not render.
+ */
+export function scanNymlBlocks(source) {
+    const out = [];
+    const comments = commentRanges(source);
+    const inComment = (pos) => comments.some(([a, b]) => pos >= a && pos < b);
+    let searchFrom = 0;
+    while (searchFrom < source.length) {
+        const open = source.indexOf(OPEN, searchFrom);
+        if (open === -1)
+            break;
+        const close = findClosing(source, open + OPEN.length);
+        if (close === -1)
+            break;
+        if (!inComment(open)) {
+            const inner = source.slice(open + OPEN.length, close);
+            const { kind, fields } = parseBody(inner);
+            out.push({ kind, fields, start: open, end: close + 2 });
+        }
+        searchFrom = close + 2;
+    }
+    return out;
+}

package/dist/doc/page-css.js

@@ -0,0 +1,230 @@
+/**
+ * Page CSS — M5.
+ *
+ * Turns a fully-resolved {@link DocSettings} into the `@page` rules, margin-box
+ * running headers/footers, page-number counters, `:root` design tokens, and
+ * layout-behavior CSS that paged.js realizes into physical page boxes.
+ *
+ * Behavior SPEC: `docs/document-model.md`; token set + page model:
+ * `docs/dom-contract.md`. Reimplemented cleanly in TS (light-only output).
+ */
+import { fontPreset } from './fonts.js';
+/* ─────────────────────────── helpers ─────────────────────────── */
+/** Escape a user string for safe use inside a CSS `content: "..."` value. */
+function cssString(raw) {
+    return '"' + raw.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+}
+/** Named page sizes pass straight through; a custom string passes through too. */
+function pageSizeValue(size) {
+    return size.trim();
+}
+/** The margin-box at-rule name for a page-number / header / footer position. */
+function marginBoxName(pos) {
+    switch (pos) {
+        case 'header-left':
+            return '@top-left';
+        case 'header-center':
+            return '@top-center';
+        case 'header-right':
+            return '@top-right';
+        case 'footer-left':
+            return '@bottom-left';
+        case 'footer-center':
+            return '@bottom-center';
+        case 'footer-right':
+            return '@bottom-right';
+        default:
+            return null;
+    }
+}
+/** The `content` expression for a page-number style. */
+function pageNumberExpr(style) {
+    switch (style) {
+        case 'simple':
+            return 'counter(page)';
+        case 'page-n':
+            return '"Page " counter(page)';
+        case 'page-n-of-N':
+            return '"Page " counter(page) " of " counter(pages)';
+        case 'n-of-N':
+            return 'counter(page) " of " counter(pages)';
+        case 'n-slash-N':
+            return 'counter(page) " / " counter(pages)';
+        case 'dash-n-dash':
+            return '"— " counter(page) " —"';
+        case 'brackets':
+            return '"[" counter(page) "]"';
+        case 'parentheses':
+            return '"(" counter(page) ")"';
+        default:
+            return 'counter(page)';
+    }
+}
+/* ─────────────────────────── builder ─────────────────────────── */
+/**
+ * Build the full page CSS string for a document. Pure: depends only on `s`.
+ */
+export function buildPageCss(s) {
+    // Font family is explicit only when the user/template set fontFamily or
+    // fontPreset; otherwise leave it to the theme (or base.css fallback).
+    const bodyFamily = s.fontFamily ?? (s.fontPreset ? fontPreset(s.fontPreset).family : undefined);
+    const headingFamily = s.fontHeadingPreset ? fontPreset(s.fontHeadingPreset).family : bodyFamily;
+    const marginBoxFamily = s.fontMarginBoxPreset
+        ? fontPreset(s.fontMarginBoxPreset).family
+        : (bodyFamily ?? 'system-ui, "Segoe UI", Helvetica, Arial, sans-serif');
+    const headerRuleColor = s.headerRuleColor || s.decorationColor;
+    const footerRuleColor = s.footerRuleColor || s.decorationColor;
+    // Collect the margin-box declarations for the @page rule. Each value is the
+    // inner CSS (content + any per-box styling) keyed by margin-box at-rule.
+    const boxes = new Map();
+    const addBox = (name, decl) => {
+        const list = boxes.get(name);
+        if (list)
+            list.push(decl);
+        else
+            boxes.set(name, [decl]);
+    };
+    // Static running headers/footers.
+    const headerFs = `font-size: ${s.headerFontSize}pt;`;
+    const footerFs = `font-size: ${s.footerFontSize}pt;`;
+    const addStatic = (name, text, fontSize) => {
+        if (text && text.length > 0) {
+            addBox(name, `content: ${cssString(text)}; ${fontSize}`);
+        }
+    };
+    addStatic('@top-left', s.headerLeft, headerFs);
+    addStatic('@top-center', s.headerCenter, headerFs);
+    addStatic('@top-right', s.headerRight, headerFs);
+    addStatic('@bottom-left', s.footerLeft, footerFs);
+    addStatic('@bottom-center', s.footerCenter, footerFs);
+    addStatic('@bottom-right', s.footerRight, footerFs);
+    // Page number → its margin box. A page number wins the `content` of its box
+    // (so it isn't double-declared with a static header/footer in the same box).
+    const pnBox = marginBoxName(s.pageNumberPosition);
+    if (pnBox && s.pageNumberPosition !== 'none') {
+        let expr = pageNumberExpr(s.pageNumberStyle);
+        // With clean front matter the body is renumbered from 1. paged.js' own page
+        // counter / counter-reset is unreliable across later page breaks, so the
+        // engine numbers body pages in JS after layout and feeds the values through
+        // CSS vars: --orz-pageno (this page's body number, set per page) and
+        // --orz-body-pages (body total = physical − front-matter pages). Both fall
+        // back to the native counters when unset (no front matter / pre-measure).
+        if (s.frontMatterClean) {
+            expr = expr
+                .replace(/counter\(pages\)/g, 'var(--orz-body-pages, counter(pages))')
+                .replace(/counter\(page\)/g, 'var(--orz-pageno, counter(page))');
+        }
+        const isHeader = s.pageNumberPosition.startsWith('header-');
+        const fontSize = isHeader ? headerFs : footerFs;
+        boxes.set(pnBox, [`content: ${expr}; ${fontSize}`]);
+    }
+    // Header/footer rule lines: drawn via a margin-box border. A rule applies to
+    // the whole edge, so attach it to the center box (always realized by paged.js).
+    if (s.headerRule) {
+        const name = '@top-center';
+        const list = boxes.get(name) ?? [];
+        list.push(`border-bottom: 0.5pt solid ${headerRuleColor};`);
+        boxes.set(name, list);
+    }
+    if (s.footerRule) {
+        const name = '@bottom-center';
+        const list = boxes.get(name) ?? [];
+        list.push(`border-top: 0.5pt solid ${footerRuleColor};`);
+        boxes.set(name, list);
+    }
+    // Assemble @page margin-box rules.
+    const marginBoxRules = [];
+    for (const [name, decls] of boxes) {
+        marginBoxRules.push(`  ${name} {\n    ${decls.join('\n    ')}\n  }`);
+    }
+    const margin = `${s.marginTop}mm ${s.marginRight}mm ${s.marginBottom}mm ${s.marginLeft}mm`;
+    const pageRule = `@page {\n` +
+        `  size: ${pageSizeValue(s.pageSize)};\n` +
+        `  margin: ${margin};\n` +
+        (marginBoxRules.length ? marginBoxRules.join('\n') + '\n' : '') +
+        `}`;
+    // First-page header/footer suppression.
+    const firstPageDecls = [];
+    if (s.firstPageHideHeader) {
+        firstPageDecls.push('  @top-left { content: none }', '  @top-center { content: none }', '  @top-right { content: none }');
+    }
+    if (s.firstPageHideFooter || s.firstPageSkipNumber) {
+        firstPageDecls.push('  @bottom-left { content: none }', '  @bottom-center { content: none }', '  @bottom-right { content: none }');
+    }
+    const firstPageRule = firstPageDecls.length
+        ? `@page:first {\n${firstPageDecls.join('\n')}\n}`
+        : '';
+    // Front-matter "clean" mode: every `placement: page` page (title / abstract /
+    // toc) is rendered on the named page `orz-front` (paged.js tags it with the
+    // class `.pagedjs_orz-front_page`). Hide its margin rows to strip the running
+    // header, footer, and page number — done via the page class, NOT `@page
+    // orz-front { @top-* { content: none } }`, because paged.js leaks that
+    // `content: none` onto the base @page and blanks every page's chrome. Body
+    // renumbering is done in JS (per-page --orz-pageno), so no counter-reset here.
+    const frontMatterRule = s.frontMatterClean
+        ? `.pagedjs_orz-front_page .pagedjs_margin-top,\n` +
+            `.pagedjs_orz-front_page .pagedjs_margin-bottom { display: none; }`
+        : '';
+    // :root design tokens (dom-contract).
+    const rootVars = [
+        `  --page-size: ${pageSizeValue(s.pageSize)};`,
+        `  --margin-t: ${s.marginTop}mm;`,
+        `  --margin-b: ${s.marginBottom}mm;`,
+        `  --margin-l: ${s.marginLeft}mm;`,
+        `  --margin-r: ${s.marginRight}mm;`,
+        `  --font-margin-box: ${marginBoxFamily};`,
+        `  --font-size: ${s.fontSize}pt;`,
+        `  --line-height: ${s.lineHeight};`,
+    ];
+    // Look tokens: emit only when explicitly set, so a theme's own font / accent /
+    // page background apply by default and an explicit setting still wins (this
+    // sheet is added last). header/footer rules follow the accent when unset.
+    if (bodyFamily)
+        rootVars.push(`  --font-body: ${bodyFamily};`);
+    if (headingFamily)
+        rootVars.push(`  --font-heading: ${headingFamily};`);
+    if (s.decorationColor)
+        rootVars.push(`  --accent: ${s.decorationColor};`);
+    if (s.pageBackground)
+        rootVars.push(`  --page-bg: ${s.pageBackground};`);
+    rootVars.push(`  --header-rule: ${headerRuleColor || 'var(--accent, #cccccc)'};`);
+    rootVars.push(`  --footer-rule: ${footerRuleColor || 'var(--accent, #cccccc)'};`);
+    const rootRule = `:root {\n${rootVars.join('\n')}\n}`;
+    // Body / element base styling that consumes the tokens.
+    const baseRule = `.orz-doc {\n` +
+        `  font-family: var(--font-body);\n` +
+        `  font-size: var(--font-size);\n` +
+        `  line-height: var(--line-height);\n` +
+        `}\n` +
+        `.pagedjs_margin-top, .pagedjs_margin-bottom,\n` +
+        `.pagedjs_margin-top-left, .pagedjs_margin-top-center, .pagedjs_margin-top-right,\n` +
+        `.pagedjs_margin-bottom-left, .pagedjs_margin-bottom-center, .pagedjs_margin-bottom-right {\n` +
+        `  font-family: var(--font-margin-box);\n` +
+        `}`;
+    // Layout-behavior CSS.
+    const layout = [];
+    if (s.limitImageToPage) {
+        layout.push('img { max-width: 100%; max-height: 100%; }');
+    }
+    if (s.keepImageTogether) {
+        layout.push('img, figure { break-inside: avoid; }');
+    }
+    if (s.repeatTableHeader) {
+        layout.push('thead { display: table-header-group; }');
+    }
+    if (s.avoidTableRowBreaks) {
+        layout.push('tr { break-inside: avoid; }');
+    }
+    const layoutRule = layout.join('\n');
+    return [
+        pageRule,
+        firstPageRule,
+        frontMatterRule,
+        rootRule,
+        baseRule,
+        layoutRule,
+        s.customCss ?? '',
+    ]
+        .filter((part) => part.length > 0)
+        .join('\n\n');
+}