@docx-editor.dev/core 2.27.0 → 2.29.0

package/dist/diagnostic-hints-BeVjfNOv.d.ts

@@ -0,0 +1,113 @@
+import { b as CollaborationFailureCode } from './failure-NS2lsya4.js';
+
+/**
+ * The public diagnostic vocabulary: stable codes and the buckets sizes and counts are reported
+ * in. It lives in this neutral lane so a headless runtime can name a refusal without the editor
+ * contracts; `contracts/diagnostics.ts` re-exports it for the editor's own types.
+ */
+
+/** Why a document could not be opened. @public */
+type DocumentOpenDiagnosticCode = 'open.unsupported-source' | 'open.zip-corrupt' | 'open.zip-invalid-entry-name' | 'open.zip-entry-limit' | 'open.zip-size-limit' | 'open.zip-ratio-limit' | 'open.xml-malformed' | 'open.xml-dtd-forbidden' | 'open.xml-part-size-limit' | 'open.xml-depth-limit' | 'open.xml-element-limit' | 'open.invalid-limits' | 'open.content-types-invalid' | 'open.missing-main-document' | 'open.relationships-invalid' | 'open.relationship-limit' | 'open.part-limit' | 'open.failed';
+/** Why an edit, a command or a tracked change was refused. @public */
+type EditDiagnosticCode = 'edit.read-only' | 'edit.protected-content' | 'edit.suggesting-needs-author' | 'edit.review-module-required' | 'edit.tracked-drawing-delete-unsupported' | 'edit.tracked-structure-unsupported' | 'edit.tracked-operation-unsupported' | 'edit.tracking-mode-unsupported' | 'edit.tracking-author-required' | 'edit.tracking-unsupported-host' | 'edit.revision-unsupported' | 'edit.tracking-required' | 'edit.tracked-image-replace-unsupported' | 'edit.picture-selected' | 'edit.cross-structure-join' | 'edit.indivisible-content' | 'edit.field-structure' | 'edit.section-mark' | 'edit.table-structure-unsupported' | 'edit.table-insert-refused' | 'edit.table-of-contents-refused' | 'edit.unsupported-content' | 'edit.operation-unsupported' | 'edit.unsupported-story' | 'edit.unmapped-change' | 'edit.stale-target' | 'edit.invalid-argument' | 'edit.resource-limit' | 'edit.refresh-in-progress' | 'edit.collaboration-not-ready' | 'edit.collaboration-text-limit' | 'edit.internal-invariant' | 'edit.refused';
+/** Why accepting, rejecting or re-authoring a tracked change skipped an item. @public */
+type ReviewDiagnosticCode = 'review.revision-unsupported' | 'review.incomplete-group' | 'review.retained-structure' | 'review.stale-revision';
+/** Why a font did not load. The family name is never reported. @public */
+type FontDiagnosticCode = 'font.shaper-unavailable' | 'font.load-failed' | 'font.missing' | 'font.integrity-mismatch' | 'font.malformed' | 'font.size-limit' | 'font.unsupported-face';
+/**
+ * Why the undo history did not group edits as one step. Informational: nothing was refused.
+ *
+ * @public
+ */
+type HistoryDiagnosticCode = 'history.split' | 'history.possible-ungrouped-gesture' | 'history.possible-fragmented-gesture';
+/**
+ * Why a performance summary needs attention. Informational: nothing was refused.
+ *
+ * @public
+ */
+type PerformanceDiagnosticCode = 'performance.slow-interaction';
+/** Why a custom node's stored payload could not be read. The node name is never reported. @public */
+type CustomNodeDiagnosticCode = 'custom-node.payload-invalid' | 'custom-node.payload-missing';
+/**
+ * Why a collaboration session failed or refused work: `collab.` and the session's own public
+ * {@link CollaborationFailureCode}, such as `collab.authentication-failed`.
+ *
+ * @public
+ */
+type CollaborationDiagnosticCode = `collab.${CollaborationFailureCode}`;
+/** Every public diagnostic code. Codes are stable: a new one is additive, none is renamed. @public */
+type DiagnosticCode = DocumentOpenDiagnosticCode | EditDiagnosticCode | ReviewDiagnosticCode | FontDiagnosticCode | HistoryDiagnosticCode | CustomNodeDiagnosticCode | PerformanceDiagnosticCode | CollaborationDiagnosticCode;
+/**
+ * A coarse size, in powers of two, so a size cannot single out one document.
+ * `'0-64KiB'` covers everything under 64 KiB; `'512MiB+'` everything above.
+ *
+ * @public
+ */
+type ByteSizeBucket = '0-64KiB' | '64-128KiB' | '128-256KiB' | '256-512KiB' | '512KiB-1MiB' | '1-2MiB' | '2-4MiB' | '4-8MiB' | '8-16MiB' | '16-32MiB' | '32-64MiB' | '64-128MiB' | '128-256MiB' | '256-512MiB' | '512MiB+';
+/** A coarse count: `'0'`, `'1'`, `'2-9'`, `'10-99'`, `'100-999'`, `'1000+'`. @public */
+type CountBucket = '0' | '1' | '2-9' | '10-99' | '100-999' | '1000+';
+/**
+ * Which kind of package part a failure is in, by its role, never by its name: a part's real
+ * name is file data. A name outside the standard layout reports `'other'`.
+ *
+ * @public
+ */
+type DocumentPartKind = 'package' | 'content-types' | 'relationships' | 'main-document' | 'glossary' | 'styles' | 'numbering' | 'settings' | 'web-settings' | 'font-table' | 'theme' | 'header' | 'footer' | 'footnotes' | 'endnotes' | 'comments' | 'people' | 'custom-xml' | 'document-properties' | 'media' | 'embedding' | 'other';
+/**
+ * The class of an unexpected exception, for a failure the engine did not name. The message is
+ * never reported, because it can quote document content.
+ *
+ * @public
+ */
+type DiagnosticErrorName = 'Error' | 'TypeError' | 'RangeError' | 'ReferenceError' | 'SyntaxError' | 'other';
+/** What a tracked-change request was asked to do. @public */
+type ReviewOperation = 'accept' | 'reject' | 'reassign';
+/** The kind of a tracked change, as the review queue lists it. @public */
+type ReviewChangeKind = 'insert' | 'delete' | 'replace' | 'moveFrom' | 'moveTo' | 'format' | 'paragraphMark' | 'structural';
+/**
+ * Which property change a formatting change is, by its OOXML element. A name outside this list
+ * reports `'other'`.
+ *
+ * @public
+ */
+type FormattingChangeKind = 'rPrChange' | 'pPrChange' | 'sectPrChange' | 'tblPrChange' | 'tblPrExChange' | 'tblGridChange' | 'trPrChange' | 'tcPrChange' | 'numberingChange' | 'other';
+/**
+ * Where an exception the engine did not expect was caught: the mount of an open, a later layout
+ * slice of an open, a command, a single review action, or an editing API batch.
+ *
+ * @public
+ */
+type FailureStage = 'open-mount' | 'open-layout' | 'command' | 'review-item' | 'automation';
+
+/**
+ * What a diagnostic code means and what to do about it.
+ *
+ * Both strings are constants written for developers. They never contain document content, so
+ * an exporter can send them with the event.
+ *
+ * @public
+ */
+interface DiagnosticExplanation {
+    /** One or two sentences: the cause, then the action. */
+    readonly hint: string;
+    /** The documentation anchor for this code, such as `…/guides/diagnostics#edit-read-only`. */
+    readonly docs: string;
+}
+/**
+ * What a diagnostic code means and what to do about it.
+ *
+ * @example
+ * ```ts
+ * editor.on('diagnostic', (event) => {
+ *   if (event.kind === 'edit.rejected') console.warn(explainDiagnostic(event.code).hint);
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function explainDiagnostic(code: DiagnosticCode): DiagnosticExplanation;
+/** Every public code, in declaration order. For coverage tests and catalogs. @public */
+declare function diagnosticCodes(): readonly DiagnosticCode[];
+
+export { diagnosticCodes as k, explainDiagnostic as l };
+export type { ByteSizeBucket as B, CollaborationDiagnosticCode as C, DiagnosticErrorName as D, EditDiagnosticCode as E, FailureStage as F, HistoryDiagnosticCode as H, PerformanceDiagnosticCode as P, ReviewChangeKind as R, DocumentPartKind as a, CountBucket as b, CustomNodeDiagnosticCode as c, DiagnosticCode as d, DiagnosticExplanation as e, DocumentOpenDiagnosticCode as f, FontDiagnosticCode as g, FormattingChangeKind as h, ReviewDiagnosticCode as i, ReviewOperation as j };

package/dist/{document-protection-9zpIHWTE.d.ts → document-protection-CUb55pl_.d.ts}

@@ -1,4 +1,4 @@
-import { N as OoxmlNode } from './types-barrel-BFKR8Pzp.js';
+import { N as OoxmlNode } from './types-barrel-DuC5QBNC.js';
 
 /** `ST_DocProtect`: the restriction a document asks for. `none` also stands for "no element". */
 type DocumentProtectionEdit = 'none' | 'readOnly' | 'comments' | 'trackedChanges' | 'forms';
@@ -17,4 +17,4 @@ declare const NO_DOCUMENT_PROTECTION: DocumentProtectionState;
 declare function readDocumentProtection(settingsRoot: OoxmlNode | null | undefined): DocumentProtectionState;
 
 export { NO_DOCUMENT_PROTECTION as N, readDocumentProtection as r };
-export type { DocumentProtectionState as D, DocumentProtectionEdit as a };
+export type { DocumentProtectionEdit as D, DocumentProtectionState as a };