@uniweb/press 0.4.3 → 0.4.5

package/src/docx/parseStyledString.js

@@ -1,13 +1,17 @@
 /**
- * Parses a styled string with inline HTML marks (<strong>, <em>, <u>, <a>)
- * into an array of text/link part objects with style flags.
+ * Parses a styled string with inline HTML marks (<strong>, <em>, <u>, <a>,
+ * <span data-type="math">) into an array of text / link / math part
+ * objects with style flags.
  *
  * Ported from legacy report-sdk/src/utils.js:116-186, extended to support
  * <a href="..."> hyperlinks so paragraphs with auto-linked emails and URLs
- * produce real hyperlinks in the docx output.
+ * produce real hyperlinks in the docx output, and <span data-type="math">
+ * so inline math reaches the print adapters as a structured atom rather
+ * than being walked as opaque DOM (which turns MathML into raw operator
+ * text).
  *
  * @param {string} inputString - HTML string with inline marks.
- * @returns {Array<{type: string, content: string, bold?: boolean, italics?: boolean, underline?: object, href?: string}>}
+ * @returns {Array<{type: string, content?: string, bold?: boolean, italics?: boolean, underline?: object, href?: string, latex?: string, display?: boolean}>}
  *
  * @example
  * parseStyledString('Hello <strong>World</strong>')
@@ -22,7 +26,34 @@
  * //   { type: 'text', content: 'Visit ' },
  * //   { type: 'link', content: 'Example', href: 'https://example.com' }
  * // ]
+ *
+ * @example
+ * parseStyledString('Let $G$ be a graph')   // after semantic-parser wrapping
+ * // input: 'Let <span data-type="math" data-latex="G" data-display="false">…mathml…</span> be a graph'
+ * // => [
+ * //   { type: 'text', content: 'Let ' },
+ * //   { type: 'math', latex: 'G', display: false },
+ * //   { type: 'text', content: ' be a graph' }
+ * // ]
  */
+
+// Decode HTML-attribute entities written by sequence.js's escapeAttr().
+// Inverse of the four replacements there. `&amp;` last so a literal
+// `&amp;quot;` round-trips correctly.
+function decodeAttr(s) {
+    return String(s)
+        .replace(/&quot;/g, '"')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&amp;/g, '&')
+}
+
+function readAttr(attrs, name) {
+    const re = new RegExp(`${name}="([^"]*)"`)
+    const m = attrs.match(re)
+    return m ? decodeAttr(m[1]) : null
+}
+
 export function parseStyledString(inputString) {
     const createTextPart = (content, styles) => ({
         type: 'text',
@@ -48,8 +79,7 @@ export function parseStyledString(inputString) {
 
             // Handle <a> tags as links
             if (tag === 'a' && attrs) {
-                const hrefMatch = attrs.match(/href="([^"]*)"/)
-                const href = hrefMatch?.[1]
+                const href = readAttr(attrs, 'href')
                 if (href) {
                     result.push({
                         type: 'link',
@@ -61,6 +91,29 @@ export function parseStyledString(inputString) {
                 }
             }
 
+            // Handle <span data-type="math"> as an inline atom. The inner
+            // text is the pre-compiled MathML — discarded here because
+            // print adapters consume the LaTeX source instead. Browser-
+            // side renderers don't go through parseStyledString; they use
+            // dangerouslySetInnerHTML on the original paragraph HTML where
+            // the MathML survives intact.
+            if (tag === 'span' && attrs) {
+                const dataType = readAttr(attrs, 'data-type')
+                if (dataType === 'math') {
+                    const latex = readAttr(attrs, 'data-latex') || ''
+                    const display = readAttr(attrs, 'data-display') === 'true'
+                    const id = readAttr(attrs, 'data-id')
+                    result.push({
+                        type: 'math',
+                        latex,
+                        display,
+                        ...(id ? { id } : {}),
+                    })
+                    lastIndex = offset + match.length
+                    return
+                }
+            }
+
             const newStyles = { ...styles }
             if (tag === 'strong' || tag === 'b') newStyles.bold = true
             if (tag === 'em' || tag === 'i') newStyles.italics = true

package/src/docx/units.js

@@ -73,3 +73,24 @@ export function convertCentimetersToTwip(centimeters) {
 export function convertPointsToHalfPoints(points) {
     return Math.round(points * 2)
 }
+
+// ---------------------------------------------------------------------------
+// Short aliases — for terse JSX. The longer names above remain canonical
+// (and match the docx library's own helpers); these are sugar so foundation
+// code can write `columnWidths={[cm(15), cm(4), cm(1.5), cm(4)]}` instead of
+// `[convertCentimetersToTwip(15), convertCentimetersToTwip(4), …]`.
+// ---------------------------------------------------------------------------
+
+/** Centimeters to twips. Alias of `convertCentimetersToTwip`. */
+export const cm = convertCentimetersToTwip
+
+/** Millimeters to twips. Alias of `convertMillimetersToTwip`. */
+export const mm = convertMillimetersToTwip
+
+/** Inches to twips. Alias of `convertInchesToTwip`. */
+export const inch = convertInchesToTwip
+
+/** Points to twips. There are 20 twips in a point. */
+export function pt(points) {
+    return Math.round(points * 20)
+}

package/src/format/index.jsx

@@ -0,0 +1,171 @@
+/**
+ * @uniweb/press/format — locale-aware text formatters.
+ *
+ * Stage 6.1 of kb/framework/plans/press-professional-docx.md.
+ *
+ * The same JSX feeds the React preview and the docx fragment, so
+ * these are React components that emit <span data-type="text"> and
+ * route through the standard IR walker. Each takes a `value` prop
+ * (or `from`/`to` for ranges) plus optional locale + format props,
+ * and produces a single text node with the formatted string. They
+ * are theme-aware: an active <DocumentProvider> supplies the
+ * default locale and (for currency) the default ISO code, so
+ * foundations don't have to repeat them at every call site.
+ *
+ * The motivation: foundations had been writing `String(invoice.due)`
+ * which yields `"Sat Feb 28 2026 19:00:00 GMT-0500 …"` whenever
+ * YAML eagerly turns an ISO string into a JS Date. The IR layer
+ * also has a defensive Date->ISO coercion (src/adapters/docx.js),
+ * but the right way to render dates is to choose a format
+ * explicitly via these builders.
+ */
+import { useDocumentTheme } from '../ThemeContext.js'
+
+/**
+ * Coerce a value to a JS Date for formatting. Accepts:
+ *   - Date instance (used as-is)
+ *   - ISO string ('2026-03-31')
+ *   - epoch number
+ * Returns null on invalid input so the builder renders nothing.
+ */
+function toDate(value) {
+    if (value == null || value === '') return null
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? null : value
+    }
+    const d = new Date(value)
+    return Number.isNaN(d.getTime()) ? null : d
+}
+
+/**
+ * Map our small set of format names onto Intl.DateTimeFormat option
+ * bags. 'iso' is special-cased — it returns the YYYY-MM-DD form
+ * exactly, using UTC components (not local) so a date like
+ * `2026-03-31` doesn't shift across timezones.
+ */
+const DATE_FORMATS = {
+    iso: null, // sentinel — handled before Intl
+    short: { year: 'numeric', month: 'numeric', day: 'numeric' },
+    medium: { year: 'numeric', month: 'short', day: 'numeric' },
+    long: { year: 'numeric', month: 'long', day: 'numeric' },
+    full: {
+        weekday: 'long',
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric',
+    },
+}
+
+function formatIso(d) {
+    const y = d.getUTCFullYear()
+    const m = String(d.getUTCMonth() + 1).padStart(2, '0')
+    const day = String(d.getUTCDate()).padStart(2, '0')
+    return `${y}-${m}-${day}`
+}
+
+function formatDate(value, { locale = 'en-CA', format = 'medium' } = {}) {
+    const d = toDate(value)
+    if (!d) return ''
+    if (format === 'iso') return formatIso(d)
+    const opts = DATE_FORMATS[format] || DATE_FORMATS.medium
+    try {
+        // Force UTC so date-only ISO inputs ('2026-03-31') don't drift
+        // by the local timezone — without this, en-CA in EST renders
+        // 'Mar 30, 2026' instead of 'Mar 31, 2026'.
+        return new Intl.DateTimeFormat(locale, { ...opts, timeZone: 'UTC' }).format(d)
+    } catch {
+        // Bad locale — fall back to ISO.
+        return formatIso(d)
+    }
+}
+
+function formatDateRange(from, to, opts) {
+    const f = formatDate(from, opts)
+    const t = formatDate(to, opts)
+    if (f && t) return `${f} – ${t}`
+    return f || t || ''
+}
+
+function formatCurrency(value, { locale = 'en-CA', code = 'CAD' } = {}) {
+    if (value == null || value === '') return ''
+    const n = typeof value === 'number' ? value : Number(value)
+    if (!Number.isFinite(n)) return ''
+    try {
+        return new Intl.NumberFormat(locale, {
+            style: 'currency',
+            currency: code,
+            maximumFractionDigits: 2,
+        }).format(n)
+    } catch {
+        // Unknown currency code — fall back to plain number with the code.
+        return `${n.toFixed(2)} ${code}`
+    }
+}
+
+/**
+ * Inline date — emits a single text node with a formatted date.
+ *
+ * @param {Object} props
+ * @param {Date|string|number} props.value
+ * @param {'iso'|'short'|'medium'|'long'|'full'} [props.format='medium']
+ * @param {string} [props.locale] - BCP-47. Defaults to theme.locale.
+ */
+export function DateText({ value, format = 'medium', locale }) {
+    const theme = useDocumentTheme()
+    const text = formatDate(value, {
+        locale: locale ?? theme.locale,
+        format,
+    })
+    return <span data-type="text">{text}</span>
+}
+
+/**
+ * Inline date range — emits a single text node with two formatted
+ * dates joined by an en dash. When one bound is missing, only the
+ * other one renders.
+ */
+export function DateRangeText({
+    from,
+    to,
+    period,
+    format = 'medium',
+    locale,
+}) {
+    const theme = useDocumentTheme()
+    const f = period?.from ?? from
+    const t = period?.to ?? to
+    const text = formatDateRange(f, t, {
+        locale: locale ?? theme.locale,
+        format,
+    })
+    return <span data-type="text">{text}</span>
+}
+
+/**
+ * Inline currency — emits a single text node with a locale- and
+ * code-aware money amount.
+ *
+ * @param {Object} props
+ * @param {number|string} props.value
+ * @param {string} [props.code] - ISO 4217. Defaults to theme.currency.
+ * @param {string} [props.locale]
+ */
+export function Currency({ value, code, locale }) {
+    const theme = useDocumentTheme()
+    const text = formatCurrency(value, {
+        locale: locale ?? theme.locale,
+        code: code ?? theme.currency,
+    })
+    return <span data-type="text">{text}</span>
+}
+
+/**
+ * Imperative versions for callers that need a string outside JSX
+ * (cell content building, header data, etc.). These don't touch the
+ * theme — pass locale/code explicitly.
+ */
+export const formatters = {
+    date: formatDate,
+    dateRange: formatDateRange,
+    currency: formatCurrency,
+}

package/src/index.js

@@ -17,3 +17,9 @@ export {
     compileSubtree,
     compileDocument,
 } from './compileRegistrations.js'
+export {
+    useDocumentTheme,
+    resolveThemeColor,
+    resolveThemeFont,
+    DEFAULT_THEME,
+} from './ThemeContext.js'

package/src/ir/attributes.js

@@ -46,6 +46,23 @@ const toInt = (v) => {
     return Number.isFinite(n) ? n : v
 }
 
+/**
+ * Parse a comma-separated list of integers (whitespace tolerant).
+ * Used by `data-table-column-widths`, where the attribute encodes an
+ * array of twip values like "8504,2268,851,2268". Empty / non-numeric
+ * tokens are dropped — downstream callers treat an empty array the
+ * same as "no column widths declared".
+ */
+const parseIntList = (v) => {
+    if (typeof v !== 'string') return v
+    return v
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((s) => parseInt(s, 10))
+        .filter((n) => Number.isFinite(n))
+}
+
 /**
  * Explicit attribute → IR path mapping. Entries are listed in the same
  * order as the legacy switch for ease of cross-reference.
@@ -94,6 +111,124 @@ export const attributeMap = {
     'data-borders-right-size': { path: ['borders', 'right', 'size'] },
     'data-borders-right-color': { path: ['borders', 'right', 'color'] },
 
+    // ------------------------------------------------------------------
+    // Table-cell additions (Stage 1 of the press-professional-docx plan)
+    // ------------------------------------------------------------------
+
+    // Cell shading. `data-shading-fill` is the load-bearing attribute
+    // (the solid background color). `data-shading-type` defaults to
+    // 'clear' in the adapter so a plain fill JSX prop produces a solid
+    // background without callers having to remember the OOXML idiom.
+    'data-shading-fill': { path: ['shading', 'fill'] },
+    'data-shading-color': { path: ['shading', 'color'] },
+    'data-shading-type': { path: ['shading', 'type'] },
+
+    // Vertical alignment of the cell's content. `top` | `center` | `bottom`.
+    // Maps to docx's VerticalAlignTable enum at the adapter layer.
+    'data-valign': { path: ['verticalAlign'] },
+
+    // Cell column merge: how many adjacent columns this cell spans.
+    'data-grid-span': { path: ['columnSpan'], transform: toInt },
+
+    // Cell row merge: how many rows this cell spans (vertical merge).
+    // The adapter uses docx's `rowSpan` shorthand, which expects only
+    // the *starting* cell to declare a count; library handles the
+    // merge-continue rows internally.
+    'data-row-span': { path: ['rowSpan'], transform: toInt },
+
+    // ------------------------------------------------------------------
+    // Stage 3 — paragraph polish
+    // ------------------------------------------------------------------
+
+    // Paragraph indentation. All values are twips. `firstLine` and
+    // `hanging` are positive; `left` and `right` may be negative.
+    'data-indent-left': { path: ['indent', 'left'], transform: toInt },
+    'data-indent-right': { path: ['indent', 'right'], transform: toInt },
+    'data-indent-firstline': { path: ['indent', 'firstLine'], transform: toInt },
+    'data-indent-hanging': { path: ['indent', 'hanging'], transform: toInt },
+
+    // Paragraph tab stops. JSON-encoded array of TabStopDefinition objects:
+    //   [{ position: 6804, type: 'right', leader: 'dot' }, …]
+    // Position is in twips; type is left/right/center/decimal/etc;
+    // leader is none/dot/hyphen/underscore/middleDot. Foundations
+    // typically construct these via the <Paragraph tabStops=…> prop
+    // and the unit helpers (cm, mm, inch, pt).
+    // Paragraph-level named style ('Title', 'Heading1', 'Body', …).
+    // Maps to `<w:pStyle w:val="…"/>` in the docx adapter. Distinct
+    // from the run-level `data-style` (default fallthrough), which
+    // emits `<w:rStyle>`.
+    'data-paragraph-style': { path: ['paragraphStyle'] },
+
+    'data-tab-stops': {
+        path: ['tabStops'],
+        transform: (v) => {
+            if (typeof v !== 'string') return v
+            try {
+                const parsed = JSON.parse(v)
+                return Array.isArray(parsed) ? parsed : v
+            } catch {
+                return v
+            }
+        },
+    },
+
+    // TextRun toggles — explicit map entries route the lower-case
+    // HTML attribute names to camelCase IR fields the adapter reads.
+    'data-smallcaps': { path: ['smallCaps'], transform: asTrue },
+    'data-allcaps': { path: ['allCaps'], transform: asTrue },
+    'data-strike': { path: ['strike'], transform: asTrue },
+
+    // Row-level: whether the row repeats as a header on each new page
+    // when the table breaks. Presence-only — any truthy value counts.
+    'data-row-header': { path: ['tableHeader'], transform: asTrue },
+
+    // ------------------------------------------------------------------
+    // Table-level options (Stage 1)
+    //
+    // Stored under the prefixed `tableXxx` namespace so they don't
+    // collide with the cell-level `width` / `borders` properties that
+    // existed before. `irToTable` reads these on table-typed nodes.
+    // ------------------------------------------------------------------
+
+    // Column widths in twips. Emitted as a comma-separated string on
+    // the `<table>` element by Table.jsx; parsed back to an int array
+    // here. Used with `tableLayout: 'fixed'` to lock columns; without
+    // a fixed layout, Word redistributes columns to fit content.
+    'data-table-column-widths': {
+        path: ['tableColumnWidths'],
+        transform: parseIntList,
+    },
+
+    // 'fixed' | 'autofit'. Default in the adapter is 'fixed' when
+    // tableColumnWidths is set, undefined otherwise (Word's default).
+    'data-table-layout': { path: ['tableLayout'] },
+
+    // Whole-table width. Distinct from per-cell width. Same { size, type }
+    // shape (pct/dxa/auto) as cell widths.
+    'data-table-width-size': { path: ['tableWidth', 'size'] },
+    'data-table-width-type': { path: ['tableWidth', 'type'] },
+
+    // Table-level default borders. Per-cell borders still win (and
+    // already exist via `data-borders-*`); these set the table grid.
+    'data-table-borders-top-style': { path: ['tableBorders', 'top', 'style'] },
+    'data-table-borders-top-size': { path: ['tableBorders', 'top', 'size'] },
+    'data-table-borders-top-color': { path: ['tableBorders', 'top', 'color'] },
+    'data-table-borders-bottom-style': { path: ['tableBorders', 'bottom', 'style'] },
+    'data-table-borders-bottom-size': { path: ['tableBorders', 'bottom', 'size'] },
+    'data-table-borders-bottom-color': { path: ['tableBorders', 'bottom', 'color'] },
+    'data-table-borders-left-style': { path: ['tableBorders', 'left', 'style'] },
+    'data-table-borders-left-size': { path: ['tableBorders', 'left', 'size'] },
+    'data-table-borders-left-color': { path: ['tableBorders', 'left', 'color'] },
+    'data-table-borders-right-style': { path: ['tableBorders', 'right', 'style'] },
+    'data-table-borders-right-size': { path: ['tableBorders', 'right', 'size'] },
+    'data-table-borders-right-color': { path: ['tableBorders', 'right', 'color'] },
+    'data-table-borders-insideh-style': { path: ['tableBorders', 'insideHorizontal', 'style'] },
+    'data-table-borders-insideh-size': { path: ['tableBorders', 'insideHorizontal', 'size'] },
+    'data-table-borders-insideh-color': { path: ['tableBorders', 'insideHorizontal', 'color'] },
+    'data-table-borders-insidev-style': { path: ['tableBorders', 'insideVertical', 'style'] },
+    'data-table-borders-insidev-size': { path: ['tableBorders', 'insideVertical', 'size'] },
+    'data-table-borders-insidev-color': { path: ['tableBorders', 'insideVertical', 'color'] },
+
     'data-image-type': { path: ['imageType'] },
 
     'data-floating-horizontalposition-relative': {

package/src/latex/index.js

@@ -52,3 +52,8 @@ export {
 // LaTeX strings that the adapter should pass through its body-text
 // escape pass unchanged. See src/latex/raw.js for rationale.
 export { markRawLatex, RAW_BEGIN, RAW_END } from './raw.js'
+
+// LaTeX inset formatters — generic primitives that emit \cite{...} and
+// \autoref{...} commands. Foundations supply the resolved keys; press
+// supplies the emission shape + sentinel wrapping.
+export { formatCite, formatAutoref } from './insets.js'

package/src/latex/insets.js

@@ -0,0 +1,83 @@
+/**
+ * LaTeX inset formatters.
+ *
+ * Generic helpers that emit `\cite{...}` and `\autoref{...}` commands
+ * wrapped in raw-passthrough sentinels (see `./raw.js`). Foundations
+ * substitute the result into paragraph text via the inline-inset
+ * resolution pass; the LaTeX adapter's body-text escape pass leaves
+ * sentinel-bracketed segments unescaped.
+ *
+ * **Resolution stays foundation-side.** These helpers do not know how
+ * to look up bibliography records or xref entries — that's a foundation
+ * concern (book uses a per-website cite-registry; @uniweb/kit/xref's
+ * registry handles xref ids). The foundation passes already-resolved
+ * key arrays in. Press's job is the LaTeX emission shape:
+ *
+ *   formatCite(['darwin1859', 'mendel1866'])
+ *     -> '\cite{darwin1859,mendel1866}' (sentinel-wrapped)
+ *
+ *   formatCite(['darwin1859'], { locator: '42' })
+ *     -> '\cite[42]{darwin1859}' (sentinel-wrapped)
+ *
+ *   formatCite(['darwin1859'], { suppressAuthor: true })
+ *     -> '\citeyear{darwin1859}' (sentinel-wrapped)
+ *
+ *   formatAutoref(['fig-doors', 'sec-method'])
+ *     -> '\autoref{fig-doors}, \autoref{sec-method}' (sentinel-wrapped)
+ *
+ * Why these live in press: foundations doing document output already
+ * import `@uniweb/press`. The shape of these helpers — emit-LaTeX with
+ * sentinel wrapping — is exactly press's domain. Adding them here lets
+ * any future academic foundation (`@uniweb/scholar`, a thesis-only
+ * variant, an arXiv-flavored foundation) reuse the LaTeX emission
+ * vocabulary without re-deriving it.
+ */
+
+import { markRawLatex } from './raw.js'
+
+/**
+ * Emit a biblatex `\cite` (or `\citeyear`) command for one or more
+ * pre-resolved bibliography keys. Returns an empty string when the
+ * caller has filtered out every key (no resolved cites → no command).
+ *
+ * @param {string[]} keys - Resolved bibliography keys. Foundation has
+ *   already filtered out any keys that don't appear in the website's
+ *   bibliography (biblatex would fail on unknown keys at TeX-compile
+ *   time; we drop them at substitution time so authors see clean
+ *   output even with typos).
+ * @param {Object} [options]
+ * @param {string} [options.locator] - Page or location reference,
+ *   becomes the optional `[N]` argument: `\cite[42]{key}`.
+ * @param {boolean} [options.suppressAuthor] - When true, emit
+ *   `\citeyear` instead of `\cite` (author-date styles render only the
+ *   year — useful for "(Darwin 1859)" → "1859" inline).
+ * @returns {string} Sentinel-wrapped LaTeX command, or '' when keys
+ *   is empty.
+ */
+export function formatCite(keys, options = {}) {
+    if (!Array.isArray(keys) || keys.length === 0) return ''
+    const cmd = options.suppressAuthor ? '\\citeyear' : '\\cite'
+    const list = keys.join(',')
+    const raw = options.locator
+        ? `${cmd}[${String(options.locator)}]{${list}}`
+        : `${cmd}{${list}}`
+    return markRawLatex(raw)
+}
+
+/**
+ * Emit one or more `\autoref{}` commands for pre-resolved xref ids.
+ * Multi-id clusters render as comma-separated autorefs because biblatex
+ * has no native multi-cite-style \autoref grouping; cleveref does (via
+ * \cref{a,b}) but adds a package dependency the v1 LaTeX template
+ * avoids.
+ *
+ * @param {string[]} ids - Resolved xref ids (foundation filtered out
+ *   anything not present in the xref-registry).
+ * @returns {string} Sentinel-wrapped LaTeX command(s), or '' when ids
+ *   is empty.
+ */
+export function formatAutoref(ids) {
+    if (!Array.isArray(ids) || ids.length === 0) return ''
+    const refs = ids.map((id) => `\\autoref{${id}}`).join(', ')
+    return markRawLatex(refs)
+}