@makhmudov.kay/az-editor 0.1.0-beta.2 → 0.1.0-beta.4

package/dist/library/AzDocumentEditor.d.ts

@@ -2,11 +2,19 @@ import { type CSSProperties } from 'react';
 import { type DocxEditorProps } from '@docx-editor.dev/react';
 import '@docx-editor.dev/core/styles/editor.css';
 import './editor.css';
-import { type HujjatExportOptions, type HujjatExportResult } from './hujjat/contract';
+import { type HujjatExportOptions, type HujjatExportResult, type HujjatWarning } from './hujjat/contract';
+import { type AzFontStatus } from './font-diagnostics';
 export interface EditorStatus {
     pages: number;
     loading: boolean;
     error: string | null;
+    fonts?: AzFontStatus;
+}
+export interface AzParagraphPagination {
+    keepNext?: boolean;
+    keepLines?: boolean;
+    widowControl?: boolean;
+    pageBreakBefore?: boolean;
 }
 export interface AzDocumentEditorHandle {
     save(): Promise<ArrayBuffer>;
@@ -14,6 +22,8 @@ export interface AzDocumentEditorHandle {
     exportHujjat(options: HujjatExportOptions): Promise<HujjatExportResult>;
     /** Insert a validated literal placeholder at the current selection. Not a protected chip. */
     insertVariable(key: string): void;
+    /** Applies to the current selection as one undoable editor command. */
+    setParagraphPagination(options: AzParagraphPagination): void;
     focus(): void;
     print(): Promise<void>;
 }
@@ -64,6 +74,8 @@ export interface AzDocumentEditorProps {
     onExportPdf?: () => void;
     onStatusChange?: (status: EditorStatus) => void;
     onFontError?: (message: string) => void;
+    /** Read-only diagnostics for the opened/saved snapshot; cleared when edits invalidate it. */
+    onDiagnostics?: (warnings: HujjatWarning[]) => void;
 }
 /** Local DOCX editing adapter. Font and OOXML support determine visual fidelity. */
 export declare const AzDocumentEditor: import("react").ForwardRefExoticComponent<AzDocumentEditorProps & import("react").RefAttributes<AzDocumentEditorHandle>>;

package/dist/library/AzHtmlEditor.d.ts

@@ -1,6 +1,8 @@
 import { type ReactNode } from 'react';
-import { type AzDocumentEditorProps } from './AzDocumentEditor';
+import { type AzDocumentEditorProps, type AzParagraphPagination } from './AzDocumentEditor';
 import { type HujjatHtmlResult, type HujjatWarning } from './hujjat/contract';
+import type { AzHtmlLayoutOptions } from './layout-profile';
+import type { AzFontStatus } from './font-diagnostics';
 export interface AzHtmlEditorStatus {
     phase: 'loading' | 'blocked' | 'ready' | 'exporting' | 'error';
     /** True after the first user edit; exporting does not mark a server version saved. */
@@ -8,6 +10,7 @@ export interface AzHtmlEditorStatus {
     pages: number;
     error: string | null;
     warnings: HujjatWarning[];
+    fonts?: AzFontStatus;
 }
 export interface AzHtmlExportResult extends HujjatHtmlResult {
     changed: boolean;
@@ -20,11 +23,14 @@ export interface AzHtmlEditorHandle {
     /** Retry a blocked import only after the host has obtained the user's decision. */
     acceptImportLoss(): Promise<void>;
     insertVariable(key: string): void;
+    setParagraphPagination(options: AzParagraphPagination): void;
     focus(): void;
 }
 export interface AzHtmlEditorProps extends Omit<AzDocumentEditorProps, 'document' | 'onChange' | 'onStatusChange'> {
     /** Read once per mount. Change React key after resolving unsaved edits to load another version. */
     initialHtml: string;
+    /** Fixed for this draft, like initialHtml. Remount with a new key to change it. */
+    layout?: AzHtmlLayoutOptions;
     onStatusChange?: (status: AzHtmlEditorStatus) => void;
     /** Dirty notification, not serialized HTML. Call exportHtml before applying the draft. */
     onChange?: () => void;

package/dist/library/document-diagnostics.d.ts

@@ -0,0 +1,3 @@
+import { type HujjatWarning } from './hujjat/contract';
+/** Read-only source-snapshot diagnostics. Never normalizes or repacks the document. */
+export declare function analyzeDocxFormatting(bytes: Uint8Array | ArrayBuffer): Promise<HujjatWarning[]>;

package/dist/library/font-diagnostics.d.ts

@@ -0,0 +1,16 @@
+import { type FontConfigurationFragment } from '@docx-editor.dev/core/editor';
+import type { DocxEditorProps } from '@docx-editor.dev/react';
+import { type HujjatWarning } from './hujjat/contract';
+export interface AzFontStatus {
+    /** Resource readiness, never a guarantee of matching Word's fonts or pagination. */
+    state: 'loading' | 'ready' | 'degraded' | 'unknown';
+    warnings: HujjatWarning[];
+}
+/** Stable per font configuration; reset each document without replacing the resolver. */
+export declare function observeFonts(input: NonNullable<DocxEditorProps['fonts']>): {
+    fonts: FontConfigurationFragment | import("@docx-editor.dev/core").MarkedFontResolver<(request: import("@docx-editor.dev/core").FontResolutionRequest) => Promise<import("@docx-editor.dev/core").FontConfiguration | FontConfigurationFragment | undefined>>;
+    snapshot: () => AzFontStatus;
+    subscribe: (listener: () => void) => () => void;
+    fail: (code: string) => void;
+    reset: () => void;
+};

package/dist/library/hujjat/contract.d.ts

@@ -1,4 +1,6 @@
 /** Hujjat template-format-spec.ru.md, 2026-10-09. Server validation remains authoritative. */
+import type { AzHtmlLayoutOptions, AzLayoutMetadataV1 } from '../layout-profile';
+export { HUJJAT_PAGE } from '../layout-profile';
 export declare const HUJJAT_LOCALES: readonly ['uz', 'ru', 'uz_cyrl', 'en'];
 export type HujjatLocale = typeof HUJJAT_LOCALES[number];
 export interface HujjatBlock {
@@ -13,11 +15,22 @@ export interface HujjatWarning {
     code: string;
     message: string;
     severity: 'warning' | 'loss';
+    stage?: 'import' | 'edit' | 'export' | 'fonts';
+    location?: {
+        part?: string;
+        paragraphIndex?: number;
+        sectionIndex?: number;
+        htmlPath?: string;
+        runIndex?: number;
+    };
+    before?: string | number | boolean | null;
+    after?: string | number | boolean | null;
 }
 export interface HujjatHtmlResult {
     html: string;
     variables: string[];
     warnings: HujjatWarning[];
+    layout?: AzLayoutMetadataV1;
 }
 export interface HujjatExportResult extends HujjatHtmlResult {
     locales: HujjatLocales;
@@ -26,21 +39,14 @@ export interface HujjatExportOptions {
     locale: HujjatLocale;
     locales?: HujjatLocales;
     allowLossy?: boolean;
+    layout?: AzHtmlLayoutOptions;
 }
 export declare const HUJJAT_MAX_HTML_BYTES = 1048576;
-export declare const HUJJAT_PAGE: {
-    readonly widthMm: 210;
-    readonly heightMm: 297;
-    readonly topMm: 15;
-    readonly rightMm: 20;
-    readonly bottomMm: 35;
-    readonly leftMm: 20;
-};
 export declare class HujjatCompatibilityError extends Error {
     readonly warnings: HujjatWarning[];
     constructor(message: string, warnings?: HujjatWarning[]);
 }
-export declare function warn(warnings: HujjatWarning[], code: string, message: string, severity?: HujjatWarning['severity']): void;
+export declare function warn(warnings: HujjatWarning[], code: string, message: string, severity?: HujjatWarning['severity'], details?: Pick<HujjatWarning, 'stage' | 'location' | 'before' | 'after'>): void;
 export declare function assertNoLoss(warnings: HujjatWarning[], allowLossy?: boolean): void;
 export declare function validateHujjatVariable(key: string): boolean;
 export declare function hujjatFont(font: string): string;

package/dist/library/hujjat/docx-to-html.d.ts

@@ -1,5 +1,7 @@
+import type { AzHtmlLayoutOptions, AzLayoutMetadataV1 } from '../layout-profile';
 import { type HujjatWarning } from './contract';
-export declare function docxToHtml(bytes: Uint8Array | ArrayBuffer): Promise<{
+export declare function docxToHtml(bytes: Uint8Array | ArrayBuffer, options?: AzHtmlLayoutOptions): Promise<{
     html: string;
     warnings: HujjatWarning[];
+    layout?: AzLayoutMetadataV1;
 }>;

package/dist/library/hujjat/docx.d.ts

@@ -1,10 +1,13 @@
 import { type HujjatExportOptions, type HujjatExportResult, type HujjatLocales, type HujjatLocale, type HujjatHtmlResult } from './contract';
+import { type AzHtmlLayoutOptions } from '../layout-profile';
 /** Export a saved live DOCX snapshot; never scrape the paginated editor DOM. */
 export declare function exportHujjatDocx(bytes: ArrayBuffer | Uint8Array, options: HujjatExportOptions): Promise<HujjatExportResult>;
 export interface HujjatImportResult extends HujjatHtmlResult {
     document: Uint8Array<ArrayBuffer>;
 }
-/** Open only HTML-only locales. Missing locales never silently fall back when editing. */
-export declare function importHujjatTemplate(locales: HujjatLocales, locale: HujjatLocale, options?: {
+export interface HujjatImportOptions {
     allowLossy?: boolean;
-}): Promise<HujjatImportResult>;
+    layout?: AzHtmlLayoutOptions;
+}
+/** Open only HTML-only locales. Missing locales never silently fall back when editing. */
+export declare function importHujjatTemplate(locales: HujjatLocales, locale: HujjatLocale, options?: HujjatImportOptions): Promise<HujjatImportResult>;

package/dist/library/hujjat/html-to-docx.d.ts

@@ -1,3 +1,4 @@
 import { type HujjatWarning } from './contract';
+import { type AzLayoutMetadataV1 } from '../layout-profile';
 /** Deliberately bounded HTML projection, not a general browser-to-Word converter. */
-export declare function htmlToDocx(html: string, warnings: HujjatWarning[]): Promise<Uint8Array<ArrayBuffer>>;
+export declare function htmlToDocx(html: string, warnings: HujjatWarning[], layout?: AzLayoutMetadataV1): Promise<Uint8Array<ArrayBuffer>>;

package/dist/library/hujjat/page-layout.d.ts

@@ -0,0 +1,5 @@
+import { type AzHtmlLayoutOptions, type AzLayoutMetadataV1, type AzPageLayout } from '../layout-profile';
+import { type HujjatWarning } from './contract';
+export declare function pageLayoutFromSection(section: Element): AzPageLayout;
+/** Metadata is separate from HTML/locale JSON and cannot carry section boundaries. */
+export declare function readHtmlLayout(body: Element, options: AzHtmlLayoutOptions, warnings: HujjatWarning[]): AzLayoutMetadataV1 | undefined;

package/dist/library/hujjat/paragraph-format.d.ts

@@ -0,0 +1,10 @@
+import { type Css } from './xml';
+export interface LineSpacing {
+    rule: 'auto' | 'exact' | 'atLeast';
+    value: number;
+}
+/** Resolve partial OOXML properties before reducing them to CSS. Values stay in native units. */
+export declare function resolveLineSpacing(properties: (Element | null)[]): LineSpacing | undefined;
+export declare function lineSpacingCss(spacing: LineSpacing): string;
+/** Conservative size check, not a measurement of the installed font's ascent/descent. */
+export declare function runHeightEstimate(css: Css): number;

package/dist/library/hujjat/table-grid.d.ts

@@ -0,0 +1,8 @@
+import { type HujjatWarning } from './contract';
+export interface ColumnWidth {
+    column: number;
+    span: number;
+    width: number;
+}
+/** Prefer individual columns, then merged-cell constraints; share only the unspecified remainder. */
+export declare function tableColumnWidths(count: number, total: number, constraints: ColumnWidth[], warnings: HujjatWarning[]): number[];

package/dist/library/index.d.ts

@@ -10,6 +10,11 @@ export { pdfRenderProfile } from './pdf-profile';
 export { sanitizeHujjatHtml, withHujjatLocale, readHujjatHtml, validateHujjatVariable, HujjatCompatibilityError, HUJJAT_LOCALES, HUJJAT_MAX_HTML_BYTES, HUJJAT_PAGE } from './hujjat/contract';
 export type { HujjatLocale, HujjatLocales, HujjatBlock, HujjatWarning, HujjatHtmlResult, HujjatExportOptions, HujjatExportResult } from './hujjat/contract';
 export { exportHujjatDocx, importHujjatTemplate } from './hujjat/docx';
-export type { HujjatImportResult } from './hujjat/docx';
+export type { HujjatImportResult, HujjatImportOptions } from './hujjat/docx';
+export { resolveHtmlLayout } from './layout-profile';
+export type { AzParagraphPagination } from './AzDocumentEditor';
+export { analyzeDocxFormatting } from './document-diagnostics';
+export type { AzFontStatus } from './font-diagnostics';
+export type { AzPageLayout, AzHtmlLayoutOptions, AzLayoutMetadataV1 } from './layout-profile';
 export { requestHujjatPreview, createHujjatTemplatePayload } from './hujjat/api';
 export type { HujjatPreviewOptions, HujjatTemplateMetadata } from './hujjat/api';

package/dist/library/layout-profile.d.ts

@@ -0,0 +1,37 @@
+/** Physical values use OOXML twips (1/1440 inch), avoiding repeated mm rounding. */
+export interface AzPageLayout {
+    widthTwips: number;
+    heightTwips: number;
+    orientation: 'portrait' | 'landscape';
+    margins: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+        header: number;
+        footer: number;
+        gutter: number;
+    };
+}
+export interface AzHtmlLayoutOptions {
+    page?: AzPageLayout;
+    lineSpacingPolicy?: 'normalize' | 'preserve';
+}
+export interface AzLayoutMetadataV1 {
+    schema: 'az-editor.layout';
+    version: 1;
+    page: AzPageLayout;
+    lineSpacingPolicy: 'normalize' | 'preserve';
+}
+export declare const HUJJAT_PAGE: Readonly<{
+    widthMm: 210;
+    heightMm: 297;
+    topMm: 15;
+    rightMm: 20;
+    bottomMm: 35;
+    leftMm: 20;
+}>;
+export declare function contentWidthTwips(page: AzPageLayout): number;
+/** A new, validated snapshot; callers may reuse or mutate their own input objects safely. */
+export declare function resolveHtmlLayout(options?: AzHtmlLayoutOptions): AzLayoutMetadataV1;
+export declare function samePageLayout(a: AzPageLayout, b: AzPageLayout): boolean;