@uniweb/press 0.4.4 → 0.4.6

package/src/adapters/docx.js

@@ -23,6 +23,12 @@ import {
     Table,
     TableRow,
     TableCell,
+    TableLayoutType,
+    VerticalAlign,
+    ShadingType,
+    Tab as DocxTab,
+    TabStopType,
+    LeaderType,
     ExternalHyperlink,
     InternalHyperlink,
     ImageRun,
@@ -45,6 +51,7 @@ import {
     FootnoteReferenceRun,
 } from 'docx'
 import { fetchAsset } from '../assets/fetch.js'
+import { buildStylePack } from '../styles/buildStylePack.js'
 
 // ============================================================================
 // Public API
@@ -112,8 +119,13 @@ export async function buildDocument(input, options = {}) {
 
     const {
         paragraphStyles,
+        characterStyles,
+        theme,
+        typography,
         numbering,
         pageMargin,
+        pageSize,
+        pageOrientation,
         ...documentMetadata
     } = options
 
@@ -137,13 +149,27 @@ export async function buildDocument(input, options = {}) {
     const { loadAsset } = options
     const children = await convertChildren(sections.flat(), loadAsset)
 
+    const pageOptions = {
+        pageNumbers: { start: 1, formatType: NumberFormat.DECIMAL },
+        ...(pageMargin ? { margin: pageMargin } : {}),
+    }
+    // Stage 4: page size + orientation. docx's IPageSizeAttributes
+    // requires width and height, so the orientation flag only takes
+    // effect when an explicit pageSize is set. Foundations that want
+    // orientation should pass pageSize too — pageSizes.A4 / .LETTER
+    // are exported presets.
+    if (pageSize) {
+        pageOptions.size = {
+            width: pageSize.width,
+            height: pageSize.height,
+            ...(pageOrientation ? { orientation: pageOrientation } : {}),
+        }
+    }
+
     const sectionOptions = {
         properties: {
             type: SectionType.CONTINUOUS,
-            page: {
-                pageNumbers: { start: 1, formatType: NumberFormat.DECIMAL },
-                ...(pageMargin ? { margin: pageMargin } : {}),
-            },
+            page: pageOptions,
         },
         children,
     }
@@ -199,8 +225,47 @@ export async function buildDocument(input, options = {}) {
         sections: [sectionOptions],
     }
 
-    if (paragraphStyles && paragraphStyles.length) {
-        docOptions.styles = { paragraphStyles }
+    // Stage 6.0: synthesise OOXML styles from theme.typography (or an
+    // explicit typography registry) and merge with caller-supplied
+    // paragraphStyles / characterStyles. The synthesised pack provides
+    // document defaults (so every run inherits theme.fonts.body without
+    // every TextRun emitting `data-font`), built-in style overrides
+    // (Word's Title/Heading1-6 routed through `default.*`), and named
+    // styles that builders reference via `<Paragraph role="…">` /
+    // `<TextRun role="…">`. Caller styles override on id conflict.
+    //
+    // We synthesise whenever a theme is supplied, even if its
+    // typography is partial — buildStylePack falls back to
+    // DEFAULT_THEME entries for missing roles so the docx still gets
+    // a useful style pack.
+    const stylesTheme = typography
+        ? { ...(theme || {}), typography }
+        : theme
+    if (stylesTheme) {
+        const pack = buildStylePack(stylesTheme, {
+            paragraphStyles,
+            characterStyles,
+        })
+        const stylesBlock = {}
+        if (pack.default && Object.keys(pack.default).length) {
+            stylesBlock.default = pack.default
+        }
+        if (pack.paragraphStyles.length) {
+            stylesBlock.paragraphStyles = pack.paragraphStyles
+        }
+        if (pack.characterStyles.length) {
+            stylesBlock.characterStyles = pack.characterStyles
+        }
+        if (Object.keys(stylesBlock).length) docOptions.styles = stylesBlock
+    } else if (
+        (paragraphStyles && paragraphStyles.length) ||
+        (characterStyles && characterStyles.length)
+    ) {
+        // Legacy path: caller passed only raw styles, no theme. Pass
+        // through verbatim so existing foundations keep working.
+        docOptions.styles = {}
+        if (paragraphStyles?.length) docOptions.styles.paragraphStyles = paragraphStyles
+        if (characterStyles?.length) docOptions.styles.characterStyles = characterStyles
     }
 
     if (numbering && numbering.length) {
@@ -361,7 +426,12 @@ function irToParagraph(node) {
     if (node.heading) {
         options.heading = toHeadingLevel(node.heading)
     }
-    if (node.style) {
+    // Paragraph-level named style (data-paragraph-style on the element,
+    // emitted by `<Paragraph role="…">`). Wins over node.style which is
+    // the legacy run-level 'Hyperlink' marker.
+    if (node.paragraphStyle) {
+        options.style = node.paragraphStyle
+    } else if (node.style) {
         options.style = node.style
     }
     if (node.alignment) {
@@ -374,8 +444,11 @@ function irToParagraph(node) {
         options.spacing = {}
         const before = toInt(node.spacing.before)
         const after = toInt(node.spacing.after)
+        const line = toInt(node.spacing.line)
         if (before != null) options.spacing.before = before
         if (after != null) options.spacing.after = after
+        if (line != null) options.spacing.line = line
+        if (node.spacing.lineRule) options.spacing.lineRule = node.spacing.lineRule
     }
     if (node.bullet) {
         options.bullet = { level: toInt(node.bullet.level) ?? 0 }
@@ -388,6 +461,21 @@ function irToParagraph(node) {
         const instance = toInt(node.numbering.instance)
         if (instance != null) options.numbering.instance = instance
     }
+    if (node.indent) {
+        const indent = {}
+        for (const key of ['left', 'right', 'start', 'end', 'firstLine', 'hanging']) {
+            const v = node.indent[key]
+            if (v == null) continue
+            const n = typeof v === 'string' ? parseInt(v, 10) : v
+            if (Number.isFinite(n)) indent[key] = n
+        }
+        if (Object.keys(indent).length) options.indent = indent
+    }
+    if (Array.isArray(node.tabStops) && node.tabStops.length) {
+        options.tabStops = node.tabStops
+            .map(toTabStopDefinition)
+            .filter(Boolean)
+    }
 
     const children = (node.children || []).flatMap(irToInlineChildren)
 
@@ -416,6 +504,11 @@ function irToInlineChildren(node) {
     switch (node.type) {
         case 'text':
             return irToTextRunPair(node)
+        case 'tab':
+            // Stage 3: <Tab/> inline builder. Emits a docx Tab element
+            // that interacts with the paragraph's tabStops. Wrapped in
+            // a TextRun so the OOXML parent is <w:r>.
+            return [new TextRun({ children: [new DocxTab()] })]
         case 'externalHyperlink':
             return [irToExternalHyperlink(node)]
         case 'internalHyperlink':
@@ -437,6 +530,14 @@ function irToInlineChildren(node) {
             return node.footnoteId
                 ? [new FootnoteReferenceRun(node.footnoteId)]
                 : []
+        case 'math': {
+            // v1 fallback: emit the LaTeX source as plain text. Better
+            // than the MathML soup that was leaking before this case
+            // existed (`<mo>…</mo>` operator names appearing as letters
+            // in the document). A faithful OMML emitter is tracked in
+            // kb/framework/plans/math-print-adapters.md §"Future work".
+            return [new TextRun({ text: node.latex || '' })]
+        }
         default:
             // Unknown inline: try text extraction, then recurse children.
             if (node.content) {
@@ -490,6 +591,21 @@ function irToTextRunPair(node) {
     if (node.italics === 'true' || node.italics === true) options.italics = true
     if (node.underline) options.underline = node.underline
     if (node.style) options.style = node.style
+    // Stage 1 of press-professional-docx: branded text needs color/size/font.
+    // The IR's color/size/font come from the default fallthrough rule on
+    // unknown data-* attributes (data-color, data-size, data-font set by
+    // the TextRun builder). docx@9.x expects: color = hex without '#',
+    // size = half-points (28pt = 56), font = family name string.
+    if (node.color) options.color = node.color
+    if (node.size != null) {
+        const sz = typeof node.size === 'string' ? parseInt(node.size, 10) : node.size
+        if (Number.isFinite(sz)) options.size = sz
+    }
+    if (node.font) options.font = node.font
+    // Stage 3: smallCaps / allCaps / strike — boolean run formatting.
+    if (node.smallCaps === 'true' || node.smallCaps === true) options.smallCaps = true
+    if (node.allCaps === 'true' || node.allCaps === true) options.allCaps = true
+    if (node.strike === 'true' || node.strike === true) options.strike = true
 
     result.push(new TextRun(options))
     return result
@@ -519,14 +635,53 @@ function irToTable(node) {
     const rows = (node.children || [])
         .filter((child) => child.type === 'tableRow')
         .map(irToTableRow)
-    return new Table({ rows })
+
+    const options = { rows }
+
+    // Column widths (twips array). Parsed from `data-table-column-widths`.
+    if (Array.isArray(node.tableColumnWidths) && node.tableColumnWidths.length) {
+        options.columnWidths = node.tableColumnWidths
+    }
+
+    // Layout. Default to FIXED whenever explicit column widths are
+    // present — Word's autofit otherwise redistributes the columns to
+    // fit content, undoing the foundation's layout intent. Foundations
+    // that want autofit can opt out with `layout="autofit"`.
+    if (node.tableLayout) {
+        options.layout =
+            node.tableLayout === 'autofit'
+                ? TableLayoutType.AUTOFIT
+                : TableLayoutType.FIXED
+    } else if (options.columnWidths) {
+        options.layout = TableLayoutType.FIXED
+    }
+
+    // Whole-table width (distinct from per-cell width).
+    if (node.tableWidth) {
+        options.width = toTableCellWidth(node.tableWidth)
+    }
+
+    // Table-default borders. Per-cell borders still win.
+    if (node.tableBorders) {
+        options.borders = toBorders(node.tableBorders)
+    }
+
+    return new Table(options)
 }
 
 function irToTableRow(node) {
     const children = (node.children || [])
         .filter((child) => child.type === 'tableCell')
         .map(irToTableCell)
-    return new TableRow({ children })
+
+    const options = { children }
+
+    // Header rows repeat at the top of each new page when the table breaks.
+    if (node.tableHeader) {
+        options.tableHeader = true
+    }
+
+    return new TableRow(options)
 }
 
 function irToTableCell(node) {
@@ -541,6 +696,24 @@ function irToTableCell(node) {
     if (node.borders) {
         options.borders = toBorders(node.borders)
     }
+    if (node.shading) {
+        options.shading = toShading(node.shading)
+    }
+    if (node.verticalAlign) {
+        options.verticalAlign = toVerticalAlign(node.verticalAlign)
+    }
+    // Merge spans. docx's `rowSpan` is the starting-cell shorthand —
+    // the library handles the continue cells internally, so we don't
+    // need to emit explicit vMerge=continue on subsequent rows from
+    // the foundation side.
+    if (node.columnSpan) {
+        const n = typeof node.columnSpan === 'string' ? parseInt(node.columnSpan, 10) : node.columnSpan
+        if (Number.isFinite(n) && n > 1) options.columnSpan = n
+    }
+    if (node.rowSpan) {
+        const n = typeof node.rowSpan === 'string' ? parseInt(node.rowSpan, 10) : node.rowSpan
+        if (Number.isFinite(n) && n > 1) options.rowSpan = n
+    }
 
     // Table cell children must be Paragraph or Table instances.
     const children = (node.children || []).flatMap((child) => {
@@ -669,6 +842,93 @@ function toBorders(borders) {
     return result
 }
 
+// --- Cell shading ---
+
+const SHADING_TYPES = {
+    clear: ShadingType.CLEAR,
+    nil: ShadingType.NIL,
+    solid: ShadingType.CLEAR, // alias — `solid` is the natural prop name
+    diagonalCross: ShadingType.DIAGONAL_CROSS,
+    diagonalStripe: ShadingType.DIAGONAL_STRIPE,
+    horizontalStripe: ShadingType.HORIZONTAL_STRIPE,
+    verticalStripe: ShadingType.VERTICAL_STRIPE,
+}
+
+/**
+ * Build a TableCell `shading` option from an IR shading object.
+ *
+ * Foundations almost always want a solid background: `<Td shading="4775b2">`.
+ * That JSX shorthand resolves to `{ fill: '4775b2' }` here, and we default
+ * `type: CLEAR` and `color: 'auto'` — the standard OOXML idiom for "plain
+ * fill, no overlay pattern". Without `type`, Word may render unpredictably
+ * across versions; without `color: 'auto'`, the library may emit
+ * `w:color=""` which Word repairs on open.
+ */
+function toShading(shading) {
+    const fill = shading.fill || '000000'
+    const type = SHADING_TYPES[shading.type] ?? ShadingType.CLEAR
+    const color = shading.color || 'auto'
+    return { type, fill, color }
+}
+
+// --- Cell vertical alignment ---
+
+const VERTICAL_ALIGNS = {
+    top: VerticalAlign.TOP,
+    center: VerticalAlign.CENTER,
+    middle: VerticalAlign.CENTER, // alias — natural-language CSS-ish
+    bottom: VerticalAlign.BOTTOM,
+}
+
+function toVerticalAlign(v) {
+    return VERTICAL_ALIGNS[v] ?? VerticalAlign.TOP
+}
+
+// --- Tab stops ---
+
+const TAB_STOP_TYPES = {
+    left: TabStopType.LEFT,
+    right: TabStopType.RIGHT,
+    center: TabStopType.CENTER,
+    decimal: TabStopType.DECIMAL,
+    bar: TabStopType.BAR,
+    clear: TabStopType.CLEAR,
+    end: TabStopType.END,
+    num: TabStopType.NUM,
+    start: TabStopType.START,
+}
+
+const TAB_STOP_LEADERS = {
+    none: LeaderType.NONE,
+    dot: LeaderType.DOT,
+    hyphen: LeaderType.HYPHEN,
+    underscore: LeaderType.UNDERSCORE,
+    middleDot: LeaderType.MIDDLE_DOT,
+}
+
+/**
+ * Build a docx TabStopDefinition from an IR tab-stop entry.
+ *
+ * Foundations write `tabStops={[{position: cm(12), type: 'right', leader: 'dot'}]}`
+ * on a Paragraph. The builder JSON-stringifies the array; the IR
+ * transform parses it back here we coerce strings to docx enums.
+ *
+ * @returns {{type: string, position: number, leader?: string} | null}
+ */
+function toTabStopDefinition(stop) {
+    if (!stop || typeof stop !== 'object') return null
+    const type = TAB_STOP_TYPES[stop.type] ?? TabStopType.LEFT
+    const positionRaw =
+        typeof stop.position === 'string' ? parseInt(stop.position, 10) : stop.position
+    if (!Number.isFinite(positionRaw)) return null
+    const def = { type, position: positionRaw }
+    if (stop.leader) {
+        const leader = TAB_STOP_LEADERS[stop.leader]
+        if (leader) def.leader = leader
+    }
+    return def
+}
+
 // --- Positional tab ---
 
 const TAB_ALIGNMENTS = {
@@ -838,9 +1098,14 @@ async function irToImageParagraph(node, loadAsset) {
             imageOptions.floating = node.floating
         }
 
-        return new DocxParagraph({
+        const paragraphOptions = {
             children: [new ImageRun(imageOptions)],
-        })
+        }
+        if (node.alignment) {
+            paragraphOptions.alignment = toAlignment(node.alignment)
+        }
+
+        return new DocxParagraph(paragraphOptions)
     } catch (err) {
         console.error(`Error creating image element:`, err)
         return new DocxParagraph({})

package/src/adapters/latex.js

@@ -379,6 +379,12 @@ function blockNodeToLatex(node) {
         case 'link':
             return inlineNodeToLatex(node)
 
+        case 'math':
+            // Bare math at block level (not wrapped in a paragraph). The
+            // inline emitter already produces the right `\[…\]` shape
+            // for display:true.
+            return inlineNodeToLatex(node)
+
         case 'paragraph':
             return inlineChildrenToLatex(node.children || []).trim()
 
@@ -596,6 +602,18 @@ function inlineNodeToLatex(node) {
         return `\\href{${href}}{${inner}}`
     }
 
+    if (node.type === 'math') {
+        // LaTeX is its own native math source — pass through verbatim.
+        // `$…$` for inline; `\[…\]` for display. The optional `\label{}`
+        // makes the equation referenceable from elsewhere via `\ref{}`
+        // / `\eqref{}`. The `amsmath` package (loaded by the standard
+        // preamble) provides `\eqref`; bare `\ref` works without it.
+        const display = node.display === 'true' || node.display === true
+        const src = node.latex || ''
+        const label = node.id ? `\\label{${node.id}}` : ''
+        return display ? `\\[${src}${label}\\]` : `$${src}$${label}`
+    }
+
     return ''
 }
 

package/src/adapters/typst.js

@@ -366,6 +366,12 @@ function blockNodeToTypst(node) {
         case 'link':
             return inlineNodeToTypst(node)
 
+        case 'math':
+            // Bare math at block level (when an adapter is fed a single
+            // math element rather than a paragraph wrapping one). Reuse
+            // the inline emitter so the output stays consistent.
+            return inlineNodeToTypst(node)
+
         case 'paragraph':
             return inlineChildrenToTypst(node.children || []).trim()
 
@@ -496,8 +502,14 @@ function inlineNodeToTypst(node) {
     if (node.type === 'text') {
         let text = escapeTypstInline(node.content || '')
         if (node.code === 'true') text = '`' + (node.content || '') + '`'
-        if (node.bold === 'true') text = `*${text}*`
-        if (node.italics === 'true') text = `_${text}_`
+        // Use the function form `#strong[…]` / `#emph[…]` instead of the
+        // markup form `*…*` / `_…_`. Typst's markup-mode marks fail to
+        // close when the closing character butts directly against an
+        // alphanumeric (e.g. `_journal_4` keeps emphasis open through the
+        // rest of the document, producing "unclosed delimiter" errors).
+        // The function form has no boundary requirement.
+        if (node.bold === 'true') text = `#strong[${text}]`
+        if (node.italics === 'true') text = `#emph[${text}]`
         if (node.underline && (node.underline === 'true' || typeof node.underline === 'object')) {
             text = `#underline[${text}]`
         }
@@ -510,6 +522,26 @@ function inlineNodeToTypst(node) {
         return `#link(${quoteTypstString(href)})[${inner}]`
     }
 
+    if (node.type === 'math') {
+        // Math is delegated to the mitex typst package — foundations
+        // import mitex in their preamble. mitex emits typst math
+        // content (not arbitrary markup), so the call goes inside a
+        // typst math context: `$#mitex(\`…\`)$` for inline (no space
+        // around the dollars), `$ #mitex(\`…\`) $` for display (the
+        // spaces are typst's own inline-vs-display switch).
+        //
+        // The latex source goes inside backticks (a typst raw string).
+        // mitex parses LaTeX from the raw string and re-emits typst
+        // math. No JS-side LaTeX → typst translation needed.
+        const display = node.display === 'true' || node.display === true
+        const src = node.latex || ''
+        const labelSuffix = node.id ? ` <${node.id}>` : ''
+        if (display) {
+            return `\n$ #mitex(\`${src}\`) $${labelSuffix}\n`
+        }
+        return `$#mitex(\`${src}\`)$${labelSuffix}`
+    }
+
     return ''
 }
 

package/src/compileRegistrations.js

@@ -56,13 +56,13 @@ import { runCompile, getAdapterDescriptor } from './adapters/dispatch.js'
  *   const blob = await compileTypst(compiled, { mode: 'sources', ... })
  */
 export function compileRegistrations(elements, format, options = {}) {
-    const { basePath } = options
+    const { basePath, theme } = options
     const store = createStore()
 
     renderToStaticMarkup(
         createElement(
             DocumentProvider,
-            { store, basePath },
+            { store, basePath, theme },
             elements,
         ),
     )
@@ -138,8 +138,8 @@ function warnIfEmptyRegistrations(store, format) {
  *   triggerDownload(blob, 'book.zip')
  */
 export async function compileSubtree(elements, format, options = {}) {
-    const { basePath, adapterOptions = {} } = options
-    const compiled = compileRegistrations(elements, format, { basePath })
+    const { basePath, theme, adapterOptions = {} } = options
+    const compiled = compileRegistrations(elements, format, { basePath, theme })
     return runCompile(format, compiled, adapterOptions)
 }
 

package/src/docx/BrandLogo.jsx

@@ -0,0 +1,59 @@
+/**
+ * BrandLogo — a brand image suitable for page headers, cover blocks,
+ * and watermarks.
+ *
+ * Stage 6.4 of kb/framework/plans/press-professional-docx.md.
+ *
+ * Emits a bare `<img data-type="image">` (no Paragraph wrapper) so
+ * the IR walker keeps the image at section level — Press's docx
+ * adapter creates the carrier paragraph itself, and inline-context
+ * images are silently dropped (Image.jsx's documented contract).
+ *
+ * Alignment flows through the IR's `data-alignment` channel: the
+ * adapter applies it to the carrier paragraph before emitting the
+ * ImageRun. Foundations get a right-aligned wordmark with one prop:
+ *
+ *   <BrandLogo url={vendor.logo} width={cm(4)} align="right" />
+ *
+ * The legacy PHP-rendered Proximify invoice used a 5cm logo right-
+ * anchored in the page header. The default values match that visual.
+ */
+import Image from './Image.jsx'
+
+const DEFAULT_WIDTH = 180 // ~5 cm at the docx default DPI
+const DEFAULT_HEIGHT_RATIO = 0.32 // typical horizontal-wordmark aspect
+
+/**
+ * @param {Object} props
+ * @param {string} [props.url] - Image source. Resolved against
+ *   DocumentProvider's basePath if site-absolute. When absent, the
+ *   builder renders nothing.
+ * @param {string} [props.alt] - Accessibility text. Defaults to ''
+ *   (decorative).
+ * @param {number} [props.width=180] - Width in docx transformation
+ *   units. Use cm()/inch()/pt() for natural values.
+ * @param {number} [props.height] - Height. When omitted, defaults to
+ *   width * 0.32 (typical horizontal-wordmark aspect).
+ * @param {'left'|'center'|'right'} [props.align='right'] - Alignment of
+ *   the carrier paragraph the docx adapter wraps the ImageRun in.
+ */
+export default function BrandLogo({
+    url,
+    alt = '',
+    width = DEFAULT_WIDTH,
+    height,
+    align = 'right',
+    ...rest
+}) {
+    if (!url) return null
+    const h = height ?? Math.round(width * DEFAULT_HEIGHT_RATIO)
+    return (
+        <Image
+            data={{ url, alt }}
+            width={width}
+            height={h}
+            data-alignment={align}
+            {...rest}
+        />
+    )
+}

package/src/docx/Math.jsx

@@ -0,0 +1,22 @@
+/**
+ * Math equation — non-text inline atom. Emits a marker span the IR
+ * walker turns into a `math` IR node. The docx adapter's v1 fallback
+ * emits the LaTeX source as plain text (better than the mathml soup
+ * it was leaking before this builder existed); a faithful OMML emitter
+ * is tracked in kb/framework/plans/math-print-adapters.md §"Future work".
+ *
+ * Inline and block math share the same builder, distinguished by the
+ * `display` flag. The optional `id` flows through for parity with the
+ * typst/latex builders even though docx v1 doesn't use it.
+ *
+ * Mirrors `Image` — same role (non-text inline atom), same attribute
+ * convention, same dispatch shape on the adapter side.
+ */
+export default function Math({ latex, display = false, id, ...props }) {
+    const attrs = { 'data-type': 'math' }
+    attrs['data-latex'] = latex || ''
+    attrs['data-display'] = display ? 'true' : 'false'
+    if (id) attrs['data-id'] = id
+
+    return <span {...attrs} {...props} />
+}