@hwp-editor/react 1.0.0-rc.0

package/dist/index.d.ts

@@ -0,0 +1,471 @@
+import * as react from 'react';
+import { CSSProperties, JSX } from 'react';
+import { HwpEngine, DocumentHandle, CatEnvelope, Segment, SegmentRef, DocumentSpecV2, EditorStore, EditorState, Capabilities, ValidationReport } from '@hwp-editor/core';
+
+/**
+ * The editor's string table: one flat `<area>.<thing>` key map per locale,
+ * plus the `t()` factory that merges them.
+ *
+ * Contract (published API at 1.0.0 — a key rename is a breaking change):
+ *
+ * - `en` is canonical and is the default when no `locale` is given. It is
+ *   declared WITHOUT `as const` so its values widen to `string` / function
+ *   signatures; `const ko: MessageTable` then makes a key missing from
+ *   EITHER table a `tsc` error (a missing key is a required-property error,
+ *   an extra key an excess-property one). That two-way parity is the whole
+ *   reason for the `typeof en` spelling — a plain `Record<..., string>`
+ *   would widen every value to the union and lose per-key parameter types.
+ * - Count-bearing messages are FUNCTION values taking a single named-params
+ *   object, never positional args and never a runtime `{count}` template.
+ *   Interpolation happens inside the function body, so word order is a
+ *   per-locale choice and English can carry a real plural branch.
+ * - Merge order is `en` -> locale table -> host `messages`. An override
+ *   replaces exactly one key; every other key falls through to the locale
+ *   default. Lookup is exact string equality with no normalization.
+ *
+ * NOT in this table, deliberately (I18N-05): font names, preset profiles,
+ * the `#FF0000` placeholder sample, and the engine's `{message}` error tail.
+ * Those are document data or engine-authored prose — translating them would
+ * change what hwp-cli receives or rewrite what the engine actually said.
+ */
+declare const en: {
+    "toolbar.toolsAria": string;
+    "toolbar.readOnly": string;
+    "toolbar.pendingEdits": (p: {
+        count: number;
+    }) => string;
+    "toolbar.revert": string;
+    "toolbar.apply": string;
+    "toolbar.applyWithCount": (p: {
+        count: number;
+    }) => string;
+    "toolbar.applying": string;
+    "toolbar.newDocument": string;
+    "validation.aria": string;
+    "validation.valid": string;
+    "validation.errors": (p: {
+        count: number;
+    }) => string;
+    "canvas.aria": string;
+    "canvas.empty": string;
+    "canvas.createCta": string;
+    "canvas.emptyPages": string;
+    "page.label": (p: {
+        page: number;
+    }) => string;
+    "side.panelAria": string;
+    "tabs.para": string;
+    "tabs.table": string;
+    "tabs.fields": string;
+    "error.prefix.load": string;
+    "error.prefix.apply": string;
+    "error.prefix.compose": string;
+    "error.kind.timeout": string;
+    "error.kind.unavailable": string;
+    "error.kind.protected": string;
+    "error.kind.generic": string;
+    "compose.title": string;
+    "compose.docType": string;
+    "compose.docTypeAria": string;
+    "compose.titleLabel": string;
+    "compose.titlePlaceholder": string;
+    "compose.authorLabel": string;
+    "compose.authorPlaceholder": string;
+    "compose.bodyLabel": string;
+    "compose.bodyPlaceholder": string;
+    "compose.cancel": string;
+    "compose.submit": string;
+    "compose.submitting": string;
+    /** Filename stem used when the compose form has no title. */
+    "compose.defaultFileStem": string;
+    "presets.official": string;
+    "presets.report": string;
+    "presets.plan": string;
+    "presets.notice": string;
+    "presets.minutes": string;
+    "presets.gaejosik": string;
+    "presets.press": string;
+    "segment.panelAria": string;
+    "segment.hint": string;
+    "segment.selectedPara": (p: {
+        section: number;
+        para: number;
+    }) => string;
+    "segment.emptyPara": string;
+    "segment.replaceLabel": string;
+    "segment.replacePlaceholder": string;
+    "segment.replaceSubmit": string;
+    "segment.insertLabel": string;
+    "segment.insertPlaceholder": string;
+    "segment.insertBefore": string;
+    "segment.insertAfter": string;
+    "segment.deletePara": string;
+    "segment.alignLabel": string;
+    "segment.alignGroupAria": string;
+    "segment.alignLeft": string;
+    "segment.alignCenter": string;
+    "segment.alignRight": string;
+    "segment.alignJustify": string;
+    "segment.formatLabel": string;
+    "segment.bold": string;
+    "segment.sizePlaceholder": string;
+    "segment.sizeAria": string;
+    "segment.colorAria": string;
+    "segment.formatSubmit": string;
+    "table.panelAria": string;
+    "table.hint": string;
+    "table.tableLabel": (p: {
+        index: number;
+    }) => string;
+    "table.cellLabel": (p: {
+        row: number;
+        col: number;
+    }) => string;
+    "table.setCell": string;
+    "table.mergeAnchor": string;
+    "table.mergeWithAnchor": string;
+    "table.splitCell": string;
+    "table.rowsCols": string;
+    "table.addRow": string;
+    "table.addCol": string;
+    "table.deleteRow": string;
+    "table.deleteCol": string;
+    "table.deleteTable": string;
+    "fields.panelAria": string;
+    "fields.hint": string;
+    "fields.valuePlaceholder": string;
+    "fields.fieldValueAria": (p: {
+        name: string;
+    }) => string;
+    "fields.setValue": string;
+};
+/** The shape both locale tables must satisfy, derived from canonical `en`. */
+type MessageTable = typeof en;
+/** Every valid `t()` key. */
+type MessageKey = keyof MessageTable;
+/** Host-supplied per-key overrides; unknown keys are a `tsc` error. */
+type HwpEditorMessages = Partial<MessageTable>;
+/** Supported UI locales. Mount-time only — runtime switching is not supported. */
+type Locale = "en" | "ko";
+/**
+ * Korean chrome. These are the literals that already shipped, carried over
+ * VERBATIM (including the `...` in-progress convention, where English uses
+ * a single `…`) — they are correct and the existing suite pins them.
+ */
+declare const ko: MessageTable;
+/**
+ * Lookup function. Keys with a function value REQUIRE their params object;
+ * plain-string keys accept no second argument — both enforced per key by
+ * the conditional variadic below, so a missing or wrong params object is a
+ * compile error at the call site.
+ */
+type TFunction = <K extends MessageKey>(key: K, ...args: MessageTable[K] extends (p: infer P) => string ? [params: P] : []) => string;
+/**
+ * Build a `t()` bound to one locale and one set of host overrides.
+ * Merge order: `en` -> locale table -> `messages` (last wins, per key).
+ */
+declare function createT(locale: Locale, messages?: HwpEditorMessages): TFunction;
+
+interface HwpEditorProps {
+    /** Engine implementation (HTTP client, local adapter, mock in tests). */
+    engine: HwpEngine;
+    /** Document to open; null shows the empty state with the new-doc entry. */
+    file: DocumentHandle | null;
+    /**
+     * UI language for the editor chrome. Defaults to `"en"`. Read at mount and
+     * on change; also drives the root `lang` attribute. Document content and
+     * engine-authored error prose are never translated.
+     */
+    locale?: Locale;
+    /**
+     * Per-key overrides applied on top of the locale table. A key not listed
+     * keeps its locale default; unknown keys are a compile error.
+     */
+    messages?: HwpEditorMessages;
+    /**
+     * Force the editor read-only regardless of what the engine reports. A UI
+     * affordance, NOT an authorization boundary: a host that must actually
+     * prevent writes enforces that server-side (see the server package's
+     * `authorize` hook). Wins over an editable engine; never re-enables a
+     * document the engine reports as protected.
+     */
+    readOnly?: boolean;
+    /**
+     * Called once per completed document load, after both the read and the
+     * render resolve, with the document that was loaded. Fires again on every
+     * `file` change; never fires for `file={null}` or a load cancelled by
+     * unmount.
+     */
+    onReady?: (document: DocumentHandle) => void;
+    /**
+     * Called for every engine failure — load, apply, undo, refresh, and
+     * compose — with the caught value verbatim, so a host can branch on the
+     * stable `code` of a `HwpEngineError`. The inline alert renders either
+     * way; this is an addition to it, not a replacement.
+     */
+    onError?: (error: unknown) => void;
+    /** Called whenever the document bytes change (applied edit, undo, compose). */
+    onChange?: (document: DocumentHandle) => void;
+    /** Called when the dirty flag (pending ops queued) changes. */
+    onDirtyChange?: (dirty: boolean) => void;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Imperative surface a host reaches through `ref`. Exactly four methods at
+ * 1.0.0 and no state getters: hosts observe state through `onChange` /
+ * `onDirtyChange` / `onReady` / `onError`, which stay in sync with React
+ * rendering in a way a getter read from outside the render cycle cannot.
+ */
+interface HwpEditorHandle {
+    /**
+     * Apply the queued edit ops. Resolves without touching the engine when the
+     * queue is empty, no document is loaded, an apply is already in flight, or
+     * the editor is read-only.
+     */
+    apply(): Promise<void>;
+    /**
+     * Undo the last applied edit. Resolves without touching the engine when the
+     * snapshot stack is empty.
+     */
+    revert(): Promise<void>;
+    /**
+     * Re-read and re-render the current document after an external change.
+     * Rejects if the engine fails (after firing `onError` and showing the alert).
+     */
+    refresh(): Promise<void>;
+    /** Open the new-document compose dialog. */
+    openCompose(): void;
+}
+/**
+ * Top-level embeddable editor. Layout: toolbar (apply/revert/validation
+ * badge/pending-ops count/protected notice) | PageCanvas | side panel
+ * (SegmentInspector / TableGrid / FieldsPanel tabs). The new-document entry
+ * point opens ComposePanel.
+ */
+declare const HwpEditor: react.ForwardRefExoticComponent<HwpEditorProps & react.RefAttributes<HwpEditorHandle>>;
+
+/**
+ * Multi-page scroll of rendered pages. SVG pages render inline (sanitized);
+ * raster formats fall back to <img>. Clicks resolve to the nearest segment
+ * (see geometry.ts for the flow-model approximation), and selected/pending
+ * segments are highlighted with overlay bands.
+ */
+declare function PageCanvas(): JSX.Element;
+
+/**
+ * Inspector for a selected paragraph segment: current text plus op builders
+ * (replace, insert before/after, delete, alignment, minimal char-format).
+ * All controls queue EditOps; nothing touches the engine until Apply.
+ */
+declare function SegmentInspector(): JSX.Element;
+
+/**
+ * Table-aware editor for a selected table segment. The cell grid comes from
+ * the GFM table in the read() envelope; addressing follows the CLI's
+ * 0-based "table:row:col" grammar (row 0 = header row).
+ */
+declare function TableGrid(): JSX.Element;
+
+/**
+ * Lists `{{field}}` placeholder slots found in the read() envelope, with
+ * set-field editing and jump-to-segment on click. (The engine contract has
+ * no native field/bookmark listing; see fields.ts.)
+ */
+declare function FieldsPanel(): JSX.Element;
+
+interface ComposePanelProps {
+    /** Called with the composed document once engine.compose() succeeds. */
+    onComposed: (document: DocumentHandle) => void;
+    /** Close without composing. */
+    onClose: () => void;
+}
+/**
+ * New-document flow: preset picker + guided form (title, author,
+ * markdown-ish sections) → DocumentSpec v2 → engine.compose().
+ */
+declare function ComposePanel(props: ComposePanelProps): JSX.Element;
+
+/**
+ * Minimal SVG sanitizer for inline rendering of `hwp render --format svg`
+ * output. The CLI output is trusted, but hosts embedding arbitrary documents
+ * get script/foreignObject/event-handler removal for free.
+ *
+ * Returns "" when the payload does not parse as XML.
+ */
+declare function sanitizeSvg(svgText: string): string;
+
+/**
+ * Plain-text extraction for segment markdown slices.
+ *
+ * `hwp edit` find/anchor arguments match against the document's paragraph
+ * text, not the markdown rendering of it — so markers like `#`, `**`, and
+ * link syntax must be stripped before a segment's text is used as an op
+ * target. This is intentionally conservative: anything unrecognized is kept
+ * verbatim (a longer anchor is still a valid anchor).
+ */
+declare function plainSegmentText(markdownSlice: string): string;
+
+/**
+ * Click hit-testing and highlight placement for PageCanvas.
+ *
+ * Neither the core segment envelope nor the hwp-cli SVG renderer carries
+ * per-paragraph page geometry, so positions are estimated with a linear
+ * text-flow model: paragraphs flow in document order across pages
+ * proportionally to their markdown length. Clicks map to a global flow
+ * fraction, then to the nearest segment via the core coordinate helpers;
+ * highlight bands use the exact inverse mapping, so the visual highlight
+ * always agrees with what a click would select.
+ */
+
+/** Resolve a page click to the nearest segment. */
+declare function nearestSegment(envelope: CatEnvelope, pageIndex: number, yFraction: number, pageCount: number): Segment | undefined;
+/** Global markdown offset for a click, in flow order. */
+declare function clickOffset(envelope: CatEnvelope, pageIndex: number, yFraction: number, pageCount: number): number;
+interface SegmentBand {
+    /** 0-based page index the band is drawn on. */
+    pageIndex: number;
+    /** Band top as a percentage of page height. */
+    top: number;
+    /** Band height as a percentage of page height. */
+    height: number;
+}
+/**
+ * Estimated overlay band for a segment — the inverse of {@link clickOffset},
+ * so bands and click hit-testing stay consistent.
+ */
+declare function segmentBand(envelope: CatEnvelope, segment: Segment, pageCount: number): SegmentBand | null;
+
+/**
+ * GFM table extraction from the `hwp cat --with-segments` envelope.
+ *
+ * The CLI emits one para segment per table, covering the whole markdown
+ * table block. Table indices are 0-based in document order, matching the
+ * `hwp edit --set-cell "table:row:col=value"` coordinate grammar; within a
+ * table, row 0 is the header row and the `---` separator row is skipped.
+ */
+
+interface TableModel {
+    /** 0-based table index in document order (the CLI's `table` coordinate). */
+    tableIndex: number;
+    /** Segment covering the table block. */
+    segment: Segment;
+    /**
+     * Cell grid. Row 0 is the header row; the markdown separator row is not
+     * included. Merged cells cannot be represented in markdown, so spans are
+     * flattened to their anchor cell text.
+     */
+    rows: string[][];
+}
+/** True when a segment's markdown slice is a GFM table block. */
+declare function isTableSlice(slice: string): boolean;
+/** Parse a GFM table slice into a cell grid; null when not a table. */
+declare function parseMarkdownTable(slice: string): string[][] | null;
+/** All tables in the envelope, in document order. */
+declare function findTables(envelope: CatEnvelope): TableModel[];
+/** The table whose segment sits at the given source coordinate, if any. */
+declare function tableAtRef(envelope: CatEnvelope, ref: SegmentRef): TableModel | undefined;
+
+/**
+ * Field-slot extraction from the read() envelope.
+ *
+ * The engine contract exposes no field/bookmark registry (that would need
+ * `hwp fields` / `hwp bookmarks`), so the fields panel works with template
+ * placeholder slots — `{{name}}` markers in the markdown — which map
+ * directly onto `hwp edit --set-field "name=value"`.
+ */
+
+interface FieldSlot {
+    /** Placeholder name as written between the braces. */
+    name: string;
+    /** Segment containing the placeholder. */
+    segment: SegmentRef;
+}
+/** All `{{name}}` placeholder slots in the envelope, in document order. */
+declare function extractFieldSlots(envelope: CatEnvelope): FieldSlot[];
+
+/**
+ * Compose-panel presets → DocumentSpec v2.
+ *
+ * Profile values mirror hwp-cli's official presets
+ * (crates/hwp-convert/src/official.rs): body font, size (1/100 pt there,
+ * plain pt here), line spacing percent, and page-number footer policy.
+ */
+
+type ComposePreset = "official" | "report" | "plan" | "notice" | "minutes" | "gaejosik" | "press";
+declare const COMPOSE_PRESETS: ComposePreset[];
+interface ComposeInput {
+    title: string;
+    author: string;
+    /**
+     * Markdown-ish body: blank lines separate paragraphs; a line starting
+     * with "# " becomes a heading-styled paragraph.
+     */
+    body: string;
+}
+type ParagraphBlock = {
+    type: "paragraph";
+    style?: string;
+    runs: [{
+        type: "text";
+        text: string;
+    }];
+};
+/** Parse the guided-form body text into paragraph blocks. */
+declare function bodyToBlocks(body: string): ParagraphBlock[];
+/** Build the DocumentSpec v2 for a preset + guided form input. */
+declare function buildDocumentSpec(preset: ComposePreset, input: ComposeInput): DocumentSpecV2;
+
+interface HwpEditorContextValue {
+    engine: HwpEngine;
+    store: EditorStore;
+    /** Current store snapshot (from useSyncExternalStore). */
+    state: EditorState;
+    /** Last read() envelope for the current document; null before load. */
+    envelope: CatEnvelope | null;
+    capabilities: Capabilities | null;
+    /** False for protected/distribution documents: editing UI is disabled. */
+    editable: boolean;
+    validation: ValidationReport | null;
+    /** Queue of pending ops length convenience. */
+    applyPendingOps: () => void;
+    /** Re-read + re-render the current document after an external change. */
+    refresh: () => Promise<void>;
+    /** Open the compose panel (new-document flow). */
+    openCompose: () => void;
+    /**
+     * Message lookup bound to the active locale and host overrides. Every
+     * panel localizes through this one channel; a panel that cannot reach `t`
+     * cannot be localized at all.
+     */
+    t: TFunction;
+    /**
+     * Host error callback, passed straight through from `HwpEditorProps`. A
+     * panel that owns its own error state (ComposePanel) has no other way to
+     * reach the host; the caught value travels verbatim.
+     */
+    onError?: ((error: unknown) => void) | undefined;
+}
+declare function useHwpEditorContext(): HwpEditorContextValue;
+
+/**
+ * Engine error classification for distinct UI states, mapping a failure
+ * onto the four states the editor renders distinctly.
+ *
+ * The stable `HwpErrorCode` carried by `HwpEngineError` (@hwp-editor/core)
+ * is the preferred input: `engineErrorKind` consults it first and never
+ * reads the prose when it is present. Substring matching over the message
+ * is the documented FALLBACK for failures that carry no code — a pre-1.0
+ * server, or a maru/Tauri rejection that surfaces only a prefixed string
+ * ("hwped_read failed: cli_missing: ..."). The markers below are pinned by
+ * those engines; `classifyEngineError` stays exported for that path.
+ *
+ * This module classifies only. The human-readable badge LABELS live in the
+ * string table (`error.kind.*` in messages.ts) and are resolved by
+ * ErrorLine; nothing here renders text.
+ */
+
+type EngineErrorKind = "timeout" | "unavailable" | "protected" | "generic";
+declare function classifyEngineError(message: string): EngineErrorKind;
+
+export { COMPOSE_PRESETS, type ComposeInput, ComposePanel, type ComposePanelProps, type ComposePreset, type EngineErrorKind, type FieldSlot, FieldsPanel, HwpEditor, type HwpEditorContextValue, type HwpEditorHandle, type HwpEditorMessages, type HwpEditorProps, type Locale, type MessageKey, type MessageTable, PageCanvas, type SegmentBand, SegmentInspector, type TFunction, TableGrid, type TableModel, bodyToBlocks, buildDocumentSpec, classifyEngineError, clickOffset, createT, en, extractFieldSlots, findTables, isTableSlice, ko, nearestSegment, parseMarkdownTable, plainSegmentText, sanitizeSvg, segmentBand, tableAtRef, useHwpEditorContext };