@beyondwork/docx-react-component 1.0.101 → 1.0.103

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.101",
+  "version": "1.0.103",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [

package/src/core/commands/formatting-commands.ts

@@ -37,6 +37,7 @@ import type {
   ParagraphNode,
   TextMark,
   TextNode,
+  Mutable,
 } from "../../model/canonical-document.ts";
 
 // ---------------------------------------------------------------------------
@@ -659,7 +660,7 @@ export function applyTextMarkOperationToDocumentRange(
         updateMarks,
       );
       if (transformed.changed) {
-        block.children = transformed.nodes;
+        (block as Mutable<typeof block>).children = transformed.nodes;
         changed = true;
       }
     }
@@ -862,7 +863,7 @@ function resolveMarkUpdater(
 }
 
 function applyAlignment(
-  paragraph: ParagraphNode,
+  paragraph: Mutable<ParagraphNode>,
   alignment: FormattingAlignment,
 ): boolean {
   const nextAlignment = alignment === "justify" ? "both" : alignment;
@@ -880,7 +881,7 @@ function applyAlignment(
  * must clone first if the source is shared. Returns `false` when no change
  * occurred (already at the 0 / 8 bound, or no-op).
  */
-export function applyIndentation(paragraph: ParagraphNode, delta: -1 | 1): boolean {
+export function applyIndentation(paragraph: Mutable<ParagraphNode>, delta: -1 | 1): boolean {
   if (paragraph.numbering) {
     const nextLevel = clamp(paragraph.numbering.level + delta, 0, 8);
     if (nextLevel === paragraph.numbering.level) {
@@ -904,10 +905,10 @@ export function applyIndentation(paragraph: ParagraphNode, delta: -1 | 1): boole
     ...(paragraph.indentation ?? {}),
   };
   if (nextLeft > 0) {
-    nextIndentation.left = nextLeft;
+    (nextIndentation as Mutable<typeof nextIndentation>).left = nextLeft;
     paragraph.indentation = nextIndentation;
   } else if (paragraph.indentation) {
-    delete nextIndentation.left;
+    delete (nextIndentation as Mutable<typeof nextIndentation>).left;
     paragraph.indentation =
       Object.keys(nextIndentation).length > 0 ? nextIndentation : undefined;
   }
@@ -1042,7 +1043,7 @@ function getConsistentValue<TItem, TValue>(
 function visitParagraphBindings(
   blocks: BlockNode[],
   surfaceBlocks: SurfaceBlockSnapshot[],
-  visitor: (paragraph: ParagraphNode, surface: ParagraphSurfaceBlock) => void,
+  visitor: (paragraph: Mutable<ParagraphNode>, surface: ParagraphSurfaceBlock) => void,
 ): void {
   for (let index = 0; index < Math.min(blocks.length, surfaceBlocks.length); index += 1) {
     const block = blocks[index];
@@ -1146,7 +1147,7 @@ function transformInlineNodes(
 }
 
 function transformTextNode(
-  node: TextNode,
+  node: Mutable<TextNode>,
   start: number,
   selectionFrom: number,
   selectionTo: number,

package/src/core/commands/paragraph-layout-commands.ts

@@ -11,6 +11,7 @@ import type {
   TableCellNode,
   TableNode,
   TableRowNode,
+  Mutable,
 } from "../../model/canonical-document.ts";
 
 export interface ParagraphLayoutCommandContext {
@@ -26,7 +27,7 @@ export interface ParagraphLayoutMutationResult {
 export function setActiveParagraphIndentation(
   document: CanonicalDocumentEnvelope,
   snapshot: RuntimeRenderSnapshot,
-  indentation: ParagraphIndentation,
+  indentation: Mutable<ParagraphIndentation>,
   _context: ParagraphLayoutCommandContext,
 ): ParagraphLayoutMutationResult {
   return mutateActiveParagraph(document, snapshot, (paragraph) => {
@@ -66,7 +67,7 @@ export function setActiveParagraphTabStops(
 function mutateActiveParagraph(
   document: CanonicalDocumentEnvelope,
   snapshot: RuntimeRenderSnapshot,
-  mutate: (paragraph: ParagraphNode) => boolean,
+  mutate: (paragraph: Mutable<ParagraphNode>) => boolean,
 ): ParagraphLayoutMutationResult {
   const surface = snapshot.surface;
   if (!surface) {
@@ -190,27 +191,27 @@ function collectCanonicalParagraphs(
   return output;
 }
 
-function collectParagraphsFromTable(table: TableNode, output: ParagraphNode[]): void {
+function collectParagraphsFromTable(table: Mutable<TableNode>, output: ParagraphNode[]): void {
   for (const row of table.rows) {
     collectParagraphsFromRow(row, output);
   }
 }
 
-function collectParagraphsFromRow(row: TableRowNode, output: ParagraphNode[]): void {
+function collectParagraphsFromRow(row: Mutable<TableRowNode>, output: ParagraphNode[]): void {
   for (const cell of row.cells) {
     collectParagraphsFromCell(cell, output);
   }
 }
 
-function collectParagraphsFromCell(cell: TableCellNode, output: ParagraphNode[]): void {
+function collectParagraphsFromCell(cell: Mutable<TableCellNode>, output: ParagraphNode[]): void {
   collectCanonicalParagraphs(cell.children, output);
 }
 
 function mergeIndentationPatch(
   current: ParagraphIndentation | undefined,
-  patch: ParagraphIndentation,
+  patch: Mutable<ParagraphIndentation>,
 ): ParagraphIndentation | undefined {
-  const merged: ParagraphIndentation = {
+  const merged: Mutable<ParagraphIndentation> = {
     ...(current ?? {}),
   };
 
@@ -237,9 +238,9 @@ function mergeIndentationPatch(
 }
 
 function normalizeIndentation(
-  indentation: ParagraphIndentation,
+  indentation: Mutable<ParagraphIndentation>,
 ): ParagraphIndentation | undefined {
-  const normalized: ParagraphIndentation = {};
+  const normalized: Mutable<ParagraphIndentation> = {};
   if (indentation.left !== undefined && indentation.left > 0) {
     normalized.left = Math.round(indentation.left);
   }
@@ -250,7 +251,7 @@ function normalizeIndentation(
     normalized.firstLine = Math.round(indentation.firstLine);
   }
   if (indentation.hanging !== undefined && indentation.hanging > 0) {
-    normalized.hanging = Math.round(indentation.hanging);
+    (normalized as Mutable<typeof normalized>).hanging = Math.round(indentation.hanging);
     delete normalized.firstLine;
   }
   return Object.keys(normalized).length > 0 ? normalized : undefined;

package/src/core/commands/section-layout-commands.ts

@@ -21,6 +21,7 @@ import type {
   PageSize,
   SectionBreakNode,
   SectionProperties,
+  Mutable,
 } from "../../model/canonical-document.ts";
 import type {
   MarginPresetDefinition,
@@ -145,7 +146,7 @@ export function insertSectionBreak(
 
   const sectionTarget = resolveSectionTarget(cloned, surface.blocks, position);
   const inheritedProperties = cloneSectionProperties(sectionTarget?.properties);
-  const sectionBreak: SectionBreakNode = {
+  const sectionBreak: Mutable<SectionBreakNode> = {
     type: "section_break",
     sectionProperties: {
       ...inheritedProperties,
@@ -178,7 +179,7 @@ export function insertSectionBreakAfterSectionIndex(
   const inheritedProperties = cloneSectionProperties(
     getSectionPropertiesAtIndex(cloned, sectionIndex),
   );
-  const sectionBreak: SectionBreakNode = {
+  const sectionBreak: Mutable<SectionBreakNode> = {
     type: "section_break",
     sectionProperties: {
       ...inheritedProperties,
@@ -364,9 +365,9 @@ export function setSectionPageNumberingAtSectionIndex(
 
   const nextProperties = cloneSectionProperties(target.properties);
   if (pageNumbering === null) {
-    delete nextProperties.pageNumbering;
+    delete (nextProperties as Mutable<typeof nextProperties>).pageNumbering;
   } else {
-    nextProperties.pageNumbering = {
+    (nextProperties as Mutable<typeof nextProperties>).pageNumbering = {
       ...(target.properties?.pageNumbering ?? {}),
       ...pageNumbering,
     };
@@ -683,10 +684,10 @@ function findNearestSectionBreak(
 }
 
 function applySectionLayoutPatch(
-  existing: SectionProperties,
+  existing: Mutable<SectionProperties>,
   patch: SectionLayoutPatch,
 ): SectionProperties {
-  const result: SectionProperties = { ...existing };
+  const result: Mutable<SectionProperties> = { ...existing };
 
   if (patch.pageSize) {
     result.pageSize = {

package/src/core/commands/style-commands.ts

@@ -8,6 +8,7 @@ import type {
   DocumentRootNode,
   ParagraphNode,
   TableNode,
+  Mutable,
 } from "../../model/canonical-document.ts";
 
 type CanonicalDocumentEnvelope = PersistedEditorSnapshot["canonicalDocument"];
@@ -161,7 +162,7 @@ function isValidTableStyleId(
 function visitParagraphBindings(
   blocks: BlockNode[],
   surfaceBlocks: SurfaceBlockSnapshot[],
-  visitor: (paragraph: ParagraphNode, surface: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>) => void,
+  visitor: (paragraph: Mutable<ParagraphNode>, surface: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>) => void,
 ): void {
   for (let index = 0; index < Math.min(blocks.length, surfaceBlocks.length); index += 1) {
     const block = blocks[index];
@@ -203,7 +204,7 @@ function visitParagraphBindings(
 function visitTableBindings(
   blocks: BlockNode[],
   surfaceBlocks: SurfaceBlockSnapshot[],
-  visitor: (table: TableNode, surface: Extract<SurfaceBlockSnapshot, { kind: "table" }>) => void,
+  visitor: (table: Mutable<TableNode>, surface: Extract<SurfaceBlockSnapshot, { kind: "table" }>) => void,
 ): void {
   for (let index = 0; index < Math.min(blocks.length, surfaceBlocks.length); index += 1) {
     const block = blocks[index];

package/src/io/export/build-app-properties-xml.ts

@@ -40,10 +40,22 @@ export interface AppPropertiesStats {
   words?: number;
   /** Character count. */
   characters?: number;
+  /** Character count including spaces. */
+  charactersWithSpaces?: number;
   /** Line count. */
   lines?: number;
   /** Paragraph count. */
   paragraphs?: number;
+  /** Editing time in minutes. */
+  totalTime?: number;
+  /** Source template name. */
+  template?: string;
+  /** Source company property. */
+  company?: string;
+  /** Source manager property. */
+  manager?: string;
+  /** Document security flag. */
+  docSecurity?: number;
   /** App-version string override; defaults to the package version. */
   appVersion?: string;
   /** Application identifier override; defaults to package.json name@version. */
@@ -58,19 +70,31 @@ export function buildAppPropertiesXml(
   const pages = stats.pages ?? 0;
   const words = stats.words ?? 0;
   const characters = stats.characters ?? 0;
+  const charactersWithSpaces = stats.charactersWithSpaces;
   const lines = stats.lines ?? 0;
   const paragraphs = stats.paragraphs ?? 0;
+  const totalTime = stats.totalTime;
 
   return [
     `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`,
     `<Properties xmlns="${APP_PROPERTIES_NAMESPACE}" xmlns:vt="${APP_PROPERTIES_VT_NAMESPACE}">`,
     `  <Application>${escapeXml(application)}</Application>`,
     `  <AppVersion>${escapeXml(appVersion)}</AppVersion>`,
+    ...(stats.template ? [`  <Template>${escapeXml(stats.template)}</Template>`] : []),
     `  <Pages>${Math.max(0, Math.round(pages))}</Pages>`,
     `  <Words>${Math.max(0, Math.round(words))}</Words>`,
     `  <Characters>${Math.max(0, Math.round(characters))}</Characters>`,
+    ...(charactersWithSpaces !== undefined
+      ? [`  <CharactersWithSpaces>${Math.max(0, Math.round(charactersWithSpaces))}</CharactersWithSpaces>`]
+      : []),
     `  <Lines>${Math.max(0, Math.round(lines))}</Lines>`,
     `  <Paragraphs>${Math.max(0, Math.round(paragraphs))}</Paragraphs>`,
+    ...(totalTime !== undefined ? [`  <TotalTime>${Math.max(0, Math.round(totalTime))}</TotalTime>`] : []),
+    ...(stats.company ? [`  <Company>${escapeXml(stats.company)}</Company>`] : []),
+    ...(stats.manager ? [`  <Manager>${escapeXml(stats.manager)}</Manager>`] : []),
+    ...(stats.docSecurity !== undefined
+      ? [`  <DocSecurity>${Math.max(0, Math.round(stats.docSecurity))}</DocSecurity>`]
+      : []),
     `</Properties>`,
   ].join("\n");
 }

package/src/io/normalize/normalize-text.ts

@@ -18,6 +18,7 @@ import type {
   TextMark,
   TextNode,
   SdtNode,
+  Mutable,
 } from "../../model/canonical-document.ts";
 import type {
   ParsedAltChunkNode,
@@ -108,7 +109,7 @@ export function normalizeParsedTextDocument(
     }
   }
 
-  const content: DocumentRootNode = { type: "doc", children };
+  const content: Mutable<DocumentRootNode> = { type: "doc", children };
 
   return {
     content,
@@ -180,7 +181,7 @@ export async function normalizeParsedTextDocumentAsync(
     }
   }
 
-  const content: DocumentRootNode = { type: "doc", children };
+  const content: Mutable<DocumentRootNode> = { type: "doc", children };
 
   return {
     content,
@@ -432,7 +433,7 @@ function normalizeInlineChildren(
 
         const previous = normalized[normalized.length - 1];
         if (previous?.type === "text" && sameMarks(previous.marks, node.marks)) {
-          previous.text += node.text;
+          (previous as Mutable<typeof previous>).text += node.text;
         } else {
           normalized.push({
             type: "text",
@@ -752,7 +753,7 @@ function normalizeHyperlink(node: ParsedHyperlinkNode): {
         }
         const previous = children[children.length - 1];
         if (previous?.type === "text" && sameMarks(previous.marks, child.marks)) {
-          previous.text += child.text;
+          (previous as Mutable<typeof previous>).text += child.text;
         } else {
           children.push({
             type: "text",
@@ -835,7 +836,7 @@ function recordOpaqueFragment(
   const rangeStart = state.cursor;
   const rangeEnd = state.cursor + 1;
 
-  const record: OpaqueFragmentRecord = {
+  const record: Mutable<OpaqueFragmentRecord> = {
     fragmentId,
     payloadKind: "xml-subtree",
     payloadReference: rawXml,

package/src/io/ooxml/docprops.ts

@@ -0,0 +1,298 @@
+import type { DocumentMetadata } from "../../model/canonical-document.ts";
+import {
+  findFirstChild,
+  localName,
+  parseXml,
+  type XmlElementNode,
+  type XmlNode,
+} from "./_mini-xml.ts";
+
+export interface CorePropertiesView {
+  readonly title?: string;
+  readonly subject?: string;
+  readonly description?: string;
+  readonly creator?: string;
+  readonly language?: string;
+  readonly keywords?: string;
+  readonly category?: string;
+  readonly lastModifiedBy?: string;
+  readonly contentStatus?: string;
+  readonly revision?: string;
+  readonly version?: string;
+  readonly createdUtc?: string;
+  readonly modifiedUtc?: string;
+}
+
+export interface AppPropertiesView {
+  readonly application?: string;
+  readonly appVersion?: string;
+  readonly template?: string;
+  readonly pages?: number;
+  readonly words?: number;
+  readonly characters?: number;
+  readonly charactersWithSpaces?: number;
+  readonly totalTime?: number;
+  readonly company?: string;
+  readonly manager?: string;
+  readonly docSecurity?: number;
+}
+
+export interface CustomPropertyValue {
+  readonly name: string;
+  readonly value: string;
+  readonly valueKind: string;
+}
+
+export interface DocpropsView {
+  readonly coreProperties: CorePropertiesView | null;
+  readonly appProperties: AppPropertiesView | null;
+  readonly customProperties: ReadonlyArray<CustomPropertyValue>;
+  readonly sourcePresence: {
+    readonly core: boolean;
+    readonly app: boolean;
+    readonly custom: boolean;
+  };
+  readonly parseErrors: ReadonlyArray<{
+    readonly part: "core" | "app" | "custom";
+    readonly message: string;
+  }>;
+}
+
+export interface DocpropsParts {
+  readonly core?: Uint8Array;
+  readonly app?: Uint8Array;
+  readonly custom?: Uint8Array;
+}
+
+export interface OpcPartMap {
+  get(path: string): { bytes: Uint8Array } | undefined;
+}
+
+const CORE_PART = "/docProps/core.xml";
+const APP_PART = "/docProps/app.xml";
+const CUSTOM_PART = "/docProps/custom.xml";
+const UTF8_DECODER = new TextDecoder("utf-8", { fatal: false });
+
+export function parseDocprops(parts: DocpropsParts): DocpropsView {
+  const parseErrors: { part: "core" | "app" | "custom"; message: string }[] = [];
+
+  let coreProperties: CorePropertiesView | null = null;
+  if (parts.core) {
+    try {
+      coreProperties = parseCoreXml(decodeXmlBytes(parts.core));
+    } catch (err) {
+      parseErrors.push({
+        part: "core",
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  let appProperties: AppPropertiesView | null = null;
+  if (parts.app) {
+    try {
+      appProperties = parseAppXml(decodeXmlBytes(parts.app));
+    } catch (err) {
+      parseErrors.push({
+        part: "app",
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  let customProperties: ReadonlyArray<CustomPropertyValue> = [];
+  if (parts.custom) {
+    try {
+      customProperties = parseCustomXml(decodeXmlBytes(parts.custom));
+    } catch (err) {
+      parseErrors.push({
+        part: "custom",
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  return {
+    coreProperties,
+    appProperties,
+    customProperties,
+    sourcePresence: {
+      core: Boolean(parts.core),
+      app: Boolean(parts.app),
+      custom: Boolean(parts.custom),
+    },
+    parseErrors,
+  };
+}
+
+export function parseDocpropsFromOpcParts(parts: OpcPartMap): DocpropsView {
+  const core = parts.get(CORE_PART);
+  const app = parts.get(APP_PART);
+  const custom = parts.get(CUSTOM_PART);
+  return parseDocprops({
+    ...(core ? { core: core.bytes } : {}),
+    ...(app ? { app: app.bytes } : {}),
+    ...(custom ? { custom: custom.bytes } : {}),
+  });
+}
+
+export function parseDocumentMetadataFromOpcParts(parts: OpcPartMap): DocumentMetadata {
+  return docpropsToDocumentMetadata(parseDocpropsFromOpcParts(parts));
+}
+
+export function docpropsToDocumentMetadata(view: DocpropsView): DocumentMetadata {
+  const core = view.coreProperties;
+  const app = view.appProperties;
+  const appProperties = app ? compactObject({
+    application: app.application,
+    appVersion: app.appVersion,
+    template: app.template,
+    pages: app.pages,
+    words: app.words,
+    characters: app.characters,
+    charactersWithSpaces: app.charactersWithSpaces,
+    totalTime: app.totalTime,
+    company: app.company,
+    manager: app.manager,
+    docSecurity: app.docSecurity,
+  }) : undefined;
+  return {
+    ...(core?.title ? { title: core.title } : {}),
+    ...(core?.subject ? { subject: core.subject } : {}),
+    ...(core?.description ? { description: core.description } : {}),
+    ...(core?.creator ? { creator: core.creator } : {}),
+    ...(core?.language ? { language: core.language } : {}),
+    ...(parseKeywords(core?.keywords) ? { keywords: parseKeywords(core?.keywords) } : {}),
+    ...(core?.category ? { category: core.category } : {}),
+    ...(core?.lastModifiedBy ? { lastModifiedBy: core.lastModifiedBy } : {}),
+    ...(core?.contentStatus ? { contentStatus: core.contentStatus } : {}),
+    ...(core?.revision ? { revision: core.revision } : {}),
+    ...(core?.version ? { version: core.version } : {}),
+    ...(core?.createdUtc ? { createdUtc: core.createdUtc } : {}),
+    ...(core?.modifiedUtc ? { modifiedUtc: core.modifiedUtc } : {}),
+    ...(appProperties && Object.keys(appProperties).length > 0 ? { appProperties } : {}),
+    customProperties: Object.fromEntries(
+      view.customProperties.map((property) => [property.name, property.value]),
+    ),
+  };
+}
+
+function parseCoreXml(xml: string): CorePropertiesView {
+  const parsed = parseXml(xml);
+  const root = documentElement(parsed) ?? parsed;
+  return {
+    title: textOfFirstChild(root, "title"),
+    subject: textOfFirstChild(root, "subject"),
+    description: textOfFirstChild(root, "description"),
+    creator: textOfFirstChild(root, "creator"),
+    language: textOfFirstChild(root, "language"),
+    keywords: textOfFirstChild(root, "keywords"),
+    category: textOfFirstChild(root, "category"),
+    lastModifiedBy: textOfFirstChild(root, "lastModifiedBy"),
+    contentStatus: textOfFirstChild(root, "contentStatus"),
+    revision: textOfFirstChild(root, "revision"),
+    version: textOfFirstChild(root, "version"),
+    createdUtc: textOfFirstChild(root, "created"),
+    modifiedUtc: textOfFirstChild(root, "modified"),
+  };
+}
+
+function parseAppXml(xml: string): AppPropertiesView {
+  const parsed = parseXml(xml);
+  const root = documentElement(parsed) ?? parsed;
+  return {
+    application: textOfFirstChild(root, "Application"),
+    appVersion: textOfFirstChild(root, "AppVersion"),
+    template: textOfFirstChild(root, "Template"),
+    pages: parseNonNegativeInt(textOfFirstChild(root, "Pages")),
+    words: parseNonNegativeInt(textOfFirstChild(root, "Words")),
+    characters: parseNonNegativeInt(textOfFirstChild(root, "Characters")),
+    charactersWithSpaces: parseNonNegativeInt(textOfFirstChild(root, "CharactersWithSpaces")),
+    totalTime: parseNonNegativeInt(textOfFirstChild(root, "TotalTime")),
+    company: textOfFirstChild(root, "Company"),
+    manager: textOfFirstChild(root, "Manager"),
+    docSecurity: parseNonNegativeInt(textOfFirstChild(root, "DocSecurity")),
+  };
+}
+
+function parseCustomXml(xml: string): CustomPropertyValue[] {
+  const parsed = parseXml(xml);
+  const root = documentElement(parsed) ?? parsed;
+  const out: CustomPropertyValue[] = [];
+  for (const child of root.children as XmlNode[]) {
+    if (child.type !== "element" || localName(child.name) !== "property") {
+      continue;
+    }
+    const name = child.attributes.name;
+    if (typeof name !== "string" || name.length === 0) {
+      continue;
+    }
+    const valueNode = firstElementChild(child);
+    if (!valueNode) {
+      continue;
+    }
+    out.push({
+      name,
+      value: extractChildText(valueNode).trim(),
+      valueKind: localName(valueNode.name),
+    });
+  }
+  return out;
+}
+
+function decodeXmlBytes(bytes: Uint8Array): string {
+  return UTF8_DECODER.decode(bytes);
+}
+
+function documentElement(root: XmlElementNode): XmlElementNode | undefined {
+  for (const child of root.children) {
+    if (child.type === "element") return child;
+  }
+  return undefined;
+}
+
+function textOfFirstChild(node: XmlElementNode, name: string): string | undefined {
+  const child = findFirstChild(node, name);
+  if (!child) return undefined;
+  const raw = extractChildText(child).trim();
+  return raw.length === 0 ? undefined : raw;
+}
+
+function extractChildText(node: XmlElementNode): string {
+  let out = "";
+  for (const child of node.children) {
+    if (child.type === "text") {
+      out += child.text;
+    } else {
+      out += extractChildText(child);
+    }
+  }
+  return out;
+}
+
+function firstElementChild(node: XmlElementNode): XmlElementNode | undefined {
+  for (const child of node.children) {
+    if (child.type === "element") return child;
+  }
+  return undefined;
+}
+
+function parseNonNegativeInt(raw: string | undefined): number | undefined {
+  if (raw === undefined) return undefined;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+
+function parseKeywords(raw: string | undefined): string[] | undefined {
+  if (!raw) return undefined;
+  const keywords = raw.split(",").map((entry) => entry.trim()).filter(Boolean);
+  return keywords.length > 0 ? keywords : undefined;
+}
+
+function compactObject<T extends Record<string, string | number | undefined>>(
+  value: T,
+): { [K in keyof T]?: Exclude<T[K], undefined> } {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, entry]) => entry !== undefined),
+  ) as { [K in keyof T]?: Exclude<T[K], undefined> };
+}