@scrider/formatter 1.1.0 → 1.3.0

package/dist/index.d.cts

@@ -1,5 +1,6 @@
-import { AttributeMap, Op, Delta } from '@scrider/delta';
+import { AttributeMap, Op, Delta, InsertOp } from '@scrider/delta';
 export * from '@scrider/delta';
+export { InsertOp as ContentOp } from '@scrider/delta';
 
 /**
  * DOM Adapter Interface
@@ -1038,6 +1039,27 @@ declare const formulaFormat: Format<string>;
  */
 declare const imageFormat: Format<string>;
 
+/**
+ * Soft Line Break embed format
+ *
+ * Represents a "Shift+Enter" style line break that does NOT split the
+ * containing block (paragraph, list item, table cell, etc.). This is the
+ * Delta-level analogue of HTML `<br>` used as an inline line break and
+ * of the GFM "hard break" Markdown construct (two trailing spaces + `\n`).
+ *
+ * Delta:    `{ insert: { softBreak: true } }`
+ * HTML:     `<br data-scrider-embed>` (with the explicit marker so that
+ *           round-trip parsing can distinguish a soft break from the
+ *           placeholder `<br>` that appears inside an empty paragraph)
+ * Markdown: `  \n` (default GFM hard break) or inline `<br>` (configurable
+ *           via `softBreakStyle` option on `deltaToMarkdown`)
+ *
+ * Value is always `true` — the embed has no additional data.
+ *
+ * @see {@link https://github.github.com/gfm/#hard-line-breaks GFM hard line break}
+ */
+declare const softBreakFormat: Format<boolean>;
+
 /**
  * Video embed format
  *
@@ -1556,6 +1578,34 @@ interface DeltaToMarkdownOptions {
      * `render()` is used as HTML fallback in Markdown.
      */
     registry?: Registry;
+    /**
+     * Rendering style for `{ softBreak: true }` embeds (Phase 7 Part 0).
+     *
+     * - `'spaces'` (default): GFM-canonical hard break — two trailing spaces
+     *   followed by `\n` (`"  \n"`). Round-trips losslessly through remark.
+     * - `'html'`: inline `<br>` tag. Slightly more visible in source view
+     *   and immune to editor whitespace trimming. Recommended for the
+     *   LFM (LLM-Flavored Markdown) flavour exposed by the editor's
+     *   "source" toggle.
+     *
+     * Does not affect how soft breaks are rendered inside table cells —
+     * those always use inline `<br>` because GFM tables forbid raw `\n`.
+     *
+     * @default 'spaces'
+     */
+    softBreakStyle?: 'spaces' | 'html';
+    /**
+     * Strip trailing newlines from the final output.
+     *
+     * Useful when serialising a single block (e.g. one table for inline
+     * editing) where the GFM padding (blank line after a table, trailing
+     * paragraph newline, etc.) is not wanted. The internal structure of the
+     * markdown is unaffected — only trailing `\n+` at the very end of the
+     * returned string is removed.
+     *
+     * @default false
+     */
+    trimTrailingNewlines?: boolean;
 }
 /**
  * Convert Delta to Markdown
@@ -1661,9 +1711,39 @@ interface ParserContext {
     pushNewline(attrs?: AttributeMap): void;
 }
 /**
- * Check if remark is available
+ * Check if remark is available for synchronous use.
+ *
+ * Returns true if either:
+ *   - remark modules have been preloaded (via {@link preloadRemark} or a prior
+ *     `markdownToDelta` / `markdownToDeltaSync` call), OR
+ *   - CommonJS `require()` is available and can resolve `unified` and
+ *     `remark-parse` (Node.js without ESM-only mode).
+ *
+ * In browser ESM environments where `require` is undefined, this returns
+ * `false` until {@link preloadRemark} has been awaited at least once.
  */
 declare function isRemarkAvailable(): boolean;
+/**
+ * Preload remark modules (`unified`, `remark-parse`, `remark-gfm`, optionally
+ * `remark-math`) asynchronously. After this resolves successfully, the
+ * synchronous {@link markdownToDeltaSync} is usable in environments where
+ * `require()` is not available (e.g. browser ESM).
+ *
+ * Safe to call multiple times: subsequent calls short-circuit if modules are
+ * already loaded.
+ *
+ * @returns `true` if mandatory modules (`unified`, `remark-parse`,
+ *   `remark-gfm`) are now loaded; `false` if any required module is missing.
+ *   The function never throws — callers can branch on the boolean for
+ *   graceful degradation.
+ *
+ * @example
+ * // On editor mount:
+ * useEffect(() => {
+ *   preloadRemark();
+ * }, []);
+ */
+declare function preloadRemark(): Promise<boolean>;
 /**
  * Convert Markdown to Delta (async)
  */
@@ -1673,4 +1753,67 @@ declare function markdownToDelta(markdown: string, options?: MarkdownToDeltaOpti
  */
 declare function markdownToDeltaSync(markdown: string, options?: MarkdownToDeltaOptions): Delta;
 
-export { ALERT_TYPES, type AlertBlockData, type AlertType, type AlignType, BOX_FLOAT_VALUES, BOX_OVERFLOW_VALUES, type BlockContext, type BlockHandler, BlockHandlerRegistry, type BlockRenderOptions, type BoxBlockData, type BoxFloat, type BoxOpAttributes, type BoxOverflow, BrowserDOMAdapter, type CellAlign, type CellData, type ColumnsBlockData, type DOMAdapter, type DOMDocument, type DOMDocumentFragment, type DOMElement, type DOMNode, type DOMNodeList, type DeltaToHtmlOptions, type DeltaToMarkdownOptions, type FootnotesBlockData, type Format, type FormatDefinition, type FormatMatchResult, type FormatScope, type HtmlToDeltaOptions, type ListType, type MarkdownToDeltaOptions, NODE_TYPE, NodeDOMAdapter, Registry, type SanitizeOptions, type TableBlockData, type TableColAlignType, alertBlockHandler, alignFormat, backgroundFormat, blockFormat, blockquoteFormat, boldFormat, boxBlockHandler, browserAdapter, cloneDelta, codeBlockFormat, codeFormat, colorFormat, columnsBlockHandler, createDefaultBlockHandlers, createDefaultRegistry, defaultBlockFormats, defaultEmbedFormats, defaultFormats, defaultInlineFormats, deltaToHtml, deltaToMarkdown, dividerFormat, escapeHtml, extractBoxOpAttributes, fontFormat, footnoteRefFormat, footnotesBlockHandler, formulaFormat, getAdapter, getNamedColors, headerFormat, headerIdFormat, htmlToDelta, imageFormat, indentFormat, isAdapterAvailable, isElement, isRemarkAvailable, isTextNode, isValidColor, isValidHexColor, italicFormat, kbdFormat, linkFormat, listFormat, markFormat, markdownToDelta, markdownToDeltaSync, nodeAdapter, normalizeDelta, sanitizeDelta, sizeFormat, slugify, slugifyWithDedup, strikeFormat, subscriptFormat, superscriptFormat, tableBlockHandler, tableColAlignFormat, tableColFormat, tableHeaderFormat, tableRowFormat, toHexColor, underlineFormat, unescapeHtml, validateDelta, videoFormat };
+/**
+ * Simple-table region detection in flat Delta.
+ *
+ * Helpers for callers (e.g. editors that need to find the boundaries of a
+ * markdown-style table within a Delta op stream — for example to enter
+ * "edit as markdown source" mode on double-click of a rendered table cell).
+ *
+ * A simple-table region is a contiguous run of ops that ends, for each cell,
+ * with a `\n`-op carrying the `table-row` attribute (the standard format
+ * produced by {@link markdownToDelta} for GFM tables and consumed by
+ * {@link deltaToMarkdown}).
+ */
+
+/**
+ * Detected boundaries of a simple-table region.
+ */
+interface TableRegion {
+    /** Inclusive start index in the original ops array. */
+    startOpIdx: number;
+    /**
+     * Inclusive end index — always points at the last `\n`-op of the table
+     * (the terminator of the last cell of the last row).
+     */
+    endOpIdx: number;
+    /** Slice of the original ops array covering the region. */
+    ops: InsertOp[];
+}
+/**
+ * Predicate: this op is a `\n`-op that terminates a simple-table cell
+ * (i.e. it carries a `table-row` attribute).
+ */
+declare function isTableNewlineOp(op: Op | undefined): boolean;
+/**
+ * Find the boundaries of the simple-table region containing the given hint
+ * op index. The hint may be:
+ *   - an inline op inside a cell,
+ *   - the cell-terminating `\n`-op itself,
+ *   - any op between two table newlines.
+ *
+ * The function walks **forward** from the hint to find the nearest `\n`-op:
+ * if it does not carry a `table-row` attribute, the hint is not inside a
+ * table and `null` is returned. Otherwise the algorithm extends the region
+ * forward through contiguous table newlines and backward to the op just
+ * after the previous non-table `\n`-op (or the start of the array).
+ *
+ * @param ops - The full ops array (e.g. `delta.ops`).
+ * @param hintOpIdx - Any op index known or guessed to be within a table.
+ * @returns The detected region, or `null` if `hintOpIdx` is out of range or
+ *   not within any simple-table region.
+ *
+ * @example
+ * // After hit-testing a `<td>` element to a Delta op index:
+ * const region = extractTableRegion(state.delta.ops, hitOpIdx);
+ * if (region) {
+ *   const md = deltaToMarkdown(new Delta(region.ops), {
+ *     trimTrailingNewlines: true,
+ *   });
+ *   // replace ops in [region.startOpIdx, region.endOpIdx] with a single
+ *   // { insert: md + '\n' } op to enter source-edit mode
+ * }
+ */
+declare function extractTableRegion(ops: readonly Op[], hintOpIdx: number): TableRegion | null;
+
+export { ALERT_TYPES, type AlertBlockData, type AlertType, type AlignType, BOX_FLOAT_VALUES, BOX_OVERFLOW_VALUES, type BlockContext, type BlockHandler, BlockHandlerRegistry, type BlockRenderOptions, type BoxBlockData, type BoxFloat, type BoxOpAttributes, type BoxOverflow, BrowserDOMAdapter, type CellAlign, type CellData, type ColumnsBlockData, type DOMAdapter, type DOMDocument, type DOMDocumentFragment, type DOMElement, type DOMNode, type DOMNodeList, type DeltaToHtmlOptions, type DeltaToMarkdownOptions, type FootnotesBlockData, type Format, type FormatDefinition, type FormatMatchResult, type FormatScope, type HtmlToDeltaOptions, type ListType, type MarkdownToDeltaOptions, NODE_TYPE, NodeDOMAdapter, Registry, type SanitizeOptions, type TableBlockData, type TableColAlignType, type TableRegion, alertBlockHandler, alignFormat, backgroundFormat, blockFormat, blockquoteFormat, boldFormat, boxBlockHandler, browserAdapter, cloneDelta, codeBlockFormat, codeFormat, colorFormat, columnsBlockHandler, createDefaultBlockHandlers, createDefaultRegistry, defaultBlockFormats, defaultEmbedFormats, defaultFormats, defaultInlineFormats, deltaToHtml, deltaToMarkdown, dividerFormat, escapeHtml, extractBoxOpAttributes, extractTableRegion, fontFormat, footnoteRefFormat, footnotesBlockHandler, formulaFormat, getAdapter, getNamedColors, headerFormat, headerIdFormat, htmlToDelta, imageFormat, indentFormat, isAdapterAvailable, isElement, isRemarkAvailable, isTableNewlineOp, isTextNode, isValidColor, isValidHexColor, italicFormat, kbdFormat, linkFormat, listFormat, markFormat, markdownToDelta, markdownToDeltaSync, nodeAdapter, normalizeDelta, preloadRemark, sanitizeDelta, sizeFormat, slugify, slugifyWithDedup, softBreakFormat, strikeFormat, subscriptFormat, superscriptFormat, tableBlockHandler, tableColAlignFormat, tableColFormat, tableHeaderFormat, tableRowFormat, toHexColor, underlineFormat, unescapeHtml, validateDelta, videoFormat };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { AttributeMap, Op, Delta } from '@scrider/delta';
+import { AttributeMap, Op, Delta, InsertOp } from '@scrider/delta';
 export * from '@scrider/delta';
+export { InsertOp as ContentOp } from '@scrider/delta';
 
 /**
  * DOM Adapter Interface
@@ -1038,6 +1039,27 @@ declare const formulaFormat: Format<string>;
  */
 declare const imageFormat: Format<string>;
 
+/**
+ * Soft Line Break embed format
+ *
+ * Represents a "Shift+Enter" style line break that does NOT split the
+ * containing block (paragraph, list item, table cell, etc.). This is the
+ * Delta-level analogue of HTML `<br>` used as an inline line break and
+ * of the GFM "hard break" Markdown construct (two trailing spaces + `\n`).
+ *
+ * Delta:    `{ insert: { softBreak: true } }`
+ * HTML:     `<br data-scrider-embed>` (with the explicit marker so that
+ *           round-trip parsing can distinguish a soft break from the
+ *           placeholder `<br>` that appears inside an empty paragraph)
+ * Markdown: `  \n` (default GFM hard break) or inline `<br>` (configurable
+ *           via `softBreakStyle` option on `deltaToMarkdown`)
+ *
+ * Value is always `true` — the embed has no additional data.
+ *
+ * @see {@link https://github.github.com/gfm/#hard-line-breaks GFM hard line break}
+ */
+declare const softBreakFormat: Format<boolean>;
+
 /**
  * Video embed format
  *
@@ -1556,6 +1578,34 @@ interface DeltaToMarkdownOptions {
      * `render()` is used as HTML fallback in Markdown.
      */
     registry?: Registry;
+    /**
+     * Rendering style for `{ softBreak: true }` embeds (Phase 7 Part 0).
+     *
+     * - `'spaces'` (default): GFM-canonical hard break — two trailing spaces
+     *   followed by `\n` (`"  \n"`). Round-trips losslessly through remark.
+     * - `'html'`: inline `<br>` tag. Slightly more visible in source view
+     *   and immune to editor whitespace trimming. Recommended for the
+     *   LFM (LLM-Flavored Markdown) flavour exposed by the editor's
+     *   "source" toggle.
+     *
+     * Does not affect how soft breaks are rendered inside table cells —
+     * those always use inline `<br>` because GFM tables forbid raw `\n`.
+     *
+     * @default 'spaces'
+     */
+    softBreakStyle?: 'spaces' | 'html';
+    /**
+     * Strip trailing newlines from the final output.
+     *
+     * Useful when serialising a single block (e.g. one table for inline
+     * editing) where the GFM padding (blank line after a table, trailing
+     * paragraph newline, etc.) is not wanted. The internal structure of the
+     * markdown is unaffected — only trailing `\n+` at the very end of the
+     * returned string is removed.
+     *
+     * @default false
+     */
+    trimTrailingNewlines?: boolean;
 }
 /**
  * Convert Delta to Markdown
@@ -1661,9 +1711,39 @@ interface ParserContext {
     pushNewline(attrs?: AttributeMap): void;
 }
 /**
- * Check if remark is available
+ * Check if remark is available for synchronous use.
+ *
+ * Returns true if either:
+ *   - remark modules have been preloaded (via {@link preloadRemark} or a prior
+ *     `markdownToDelta` / `markdownToDeltaSync` call), OR
+ *   - CommonJS `require()` is available and can resolve `unified` and
+ *     `remark-parse` (Node.js without ESM-only mode).
+ *
+ * In browser ESM environments where `require` is undefined, this returns
+ * `false` until {@link preloadRemark} has been awaited at least once.
  */
 declare function isRemarkAvailable(): boolean;
+/**
+ * Preload remark modules (`unified`, `remark-parse`, `remark-gfm`, optionally
+ * `remark-math`) asynchronously. After this resolves successfully, the
+ * synchronous {@link markdownToDeltaSync} is usable in environments where
+ * `require()` is not available (e.g. browser ESM).
+ *
+ * Safe to call multiple times: subsequent calls short-circuit if modules are
+ * already loaded.
+ *
+ * @returns `true` if mandatory modules (`unified`, `remark-parse`,
+ *   `remark-gfm`) are now loaded; `false` if any required module is missing.
+ *   The function never throws — callers can branch on the boolean for
+ *   graceful degradation.
+ *
+ * @example
+ * // On editor mount:
+ * useEffect(() => {
+ *   preloadRemark();
+ * }, []);
+ */
+declare function preloadRemark(): Promise<boolean>;
 /**
  * Convert Markdown to Delta (async)
  */
@@ -1673,4 +1753,67 @@ declare function markdownToDelta(markdown: string, options?: MarkdownToDeltaOpti
  */
 declare function markdownToDeltaSync(markdown: string, options?: MarkdownToDeltaOptions): Delta;
 
-export { ALERT_TYPES, type AlertBlockData, type AlertType, type AlignType, BOX_FLOAT_VALUES, BOX_OVERFLOW_VALUES, type BlockContext, type BlockHandler, BlockHandlerRegistry, type BlockRenderOptions, type BoxBlockData, type BoxFloat, type BoxOpAttributes, type BoxOverflow, BrowserDOMAdapter, type CellAlign, type CellData, type ColumnsBlockData, type DOMAdapter, type DOMDocument, type DOMDocumentFragment, type DOMElement, type DOMNode, type DOMNodeList, type DeltaToHtmlOptions, type DeltaToMarkdownOptions, type FootnotesBlockData, type Format, type FormatDefinition, type FormatMatchResult, type FormatScope, type HtmlToDeltaOptions, type ListType, type MarkdownToDeltaOptions, NODE_TYPE, NodeDOMAdapter, Registry, type SanitizeOptions, type TableBlockData, type TableColAlignType, alertBlockHandler, alignFormat, backgroundFormat, blockFormat, blockquoteFormat, boldFormat, boxBlockHandler, browserAdapter, cloneDelta, codeBlockFormat, codeFormat, colorFormat, columnsBlockHandler, createDefaultBlockHandlers, createDefaultRegistry, defaultBlockFormats, defaultEmbedFormats, defaultFormats, defaultInlineFormats, deltaToHtml, deltaToMarkdown, dividerFormat, escapeHtml, extractBoxOpAttributes, fontFormat, footnoteRefFormat, footnotesBlockHandler, formulaFormat, getAdapter, getNamedColors, headerFormat, headerIdFormat, htmlToDelta, imageFormat, indentFormat, isAdapterAvailable, isElement, isRemarkAvailable, isTextNode, isValidColor, isValidHexColor, italicFormat, kbdFormat, linkFormat, listFormat, markFormat, markdownToDelta, markdownToDeltaSync, nodeAdapter, normalizeDelta, sanitizeDelta, sizeFormat, slugify, slugifyWithDedup, strikeFormat, subscriptFormat, superscriptFormat, tableBlockHandler, tableColAlignFormat, tableColFormat, tableHeaderFormat, tableRowFormat, toHexColor, underlineFormat, unescapeHtml, validateDelta, videoFormat };
+/**
+ * Simple-table region detection in flat Delta.
+ *
+ * Helpers for callers (e.g. editors that need to find the boundaries of a
+ * markdown-style table within a Delta op stream — for example to enter
+ * "edit as markdown source" mode on double-click of a rendered table cell).
+ *
+ * A simple-table region is a contiguous run of ops that ends, for each cell,
+ * with a `\n`-op carrying the `table-row` attribute (the standard format
+ * produced by {@link markdownToDelta} for GFM tables and consumed by
+ * {@link deltaToMarkdown}).
+ */
+
+/**
+ * Detected boundaries of a simple-table region.
+ */
+interface TableRegion {
+    /** Inclusive start index in the original ops array. */
+    startOpIdx: number;
+    /**
+     * Inclusive end index — always points at the last `\n`-op of the table
+     * (the terminator of the last cell of the last row).
+     */
+    endOpIdx: number;
+    /** Slice of the original ops array covering the region. */
+    ops: InsertOp[];
+}
+/**
+ * Predicate: this op is a `\n`-op that terminates a simple-table cell
+ * (i.e. it carries a `table-row` attribute).
+ */
+declare function isTableNewlineOp(op: Op | undefined): boolean;
+/**
+ * Find the boundaries of the simple-table region containing the given hint
+ * op index. The hint may be:
+ *   - an inline op inside a cell,
+ *   - the cell-terminating `\n`-op itself,
+ *   - any op between two table newlines.
+ *
+ * The function walks **forward** from the hint to find the nearest `\n`-op:
+ * if it does not carry a `table-row` attribute, the hint is not inside a
+ * table and `null` is returned. Otherwise the algorithm extends the region
+ * forward through contiguous table newlines and backward to the op just
+ * after the previous non-table `\n`-op (or the start of the array).
+ *
+ * @param ops - The full ops array (e.g. `delta.ops`).
+ * @param hintOpIdx - Any op index known or guessed to be within a table.
+ * @returns The detected region, or `null` if `hintOpIdx` is out of range or
+ *   not within any simple-table region.
+ *
+ * @example
+ * // After hit-testing a `<td>` element to a Delta op index:
+ * const region = extractTableRegion(state.delta.ops, hitOpIdx);
+ * if (region) {
+ *   const md = deltaToMarkdown(new Delta(region.ops), {
+ *     trimTrailingNewlines: true,
+ *   });
+ *   // replace ops in [region.startOpIdx, region.endOpIdx] with a single
+ *   // { insert: md + '\n' } op to enter source-edit mode
+ * }
+ */
+declare function extractTableRegion(ops: readonly Op[], hintOpIdx: number): TableRegion | null;
+
+export { ALERT_TYPES, type AlertBlockData, type AlertType, type AlignType, BOX_FLOAT_VALUES, BOX_OVERFLOW_VALUES, type BlockContext, type BlockHandler, BlockHandlerRegistry, type BlockRenderOptions, type BoxBlockData, type BoxFloat, type BoxOpAttributes, type BoxOverflow, BrowserDOMAdapter, type CellAlign, type CellData, type ColumnsBlockData, type DOMAdapter, type DOMDocument, type DOMDocumentFragment, type DOMElement, type DOMNode, type DOMNodeList, type DeltaToHtmlOptions, type DeltaToMarkdownOptions, type FootnotesBlockData, type Format, type FormatDefinition, type FormatMatchResult, type FormatScope, type HtmlToDeltaOptions, type ListType, type MarkdownToDeltaOptions, NODE_TYPE, NodeDOMAdapter, Registry, type SanitizeOptions, type TableBlockData, type TableColAlignType, type TableRegion, alertBlockHandler, alignFormat, backgroundFormat, blockFormat, blockquoteFormat, boldFormat, boxBlockHandler, browserAdapter, cloneDelta, codeBlockFormat, codeFormat, colorFormat, columnsBlockHandler, createDefaultBlockHandlers, createDefaultRegistry, defaultBlockFormats, defaultEmbedFormats, defaultFormats, defaultInlineFormats, deltaToHtml, deltaToMarkdown, dividerFormat, escapeHtml, extractBoxOpAttributes, extractTableRegion, fontFormat, footnoteRefFormat, footnotesBlockHandler, formulaFormat, getAdapter, getNamedColors, headerFormat, headerIdFormat, htmlToDelta, imageFormat, indentFormat, isAdapterAvailable, isElement, isRemarkAvailable, isTableNewlineOp, isTextNode, isValidColor, isValidHexColor, italicFormat, kbdFormat, linkFormat, listFormat, markFormat, markdownToDelta, markdownToDeltaSync, nodeAdapter, normalizeDelta, preloadRemark, sanitizeDelta, sizeFormat, slugify, slugifyWithDedup, softBreakFormat, strikeFormat, subscriptFormat, superscriptFormat, tableBlockHandler, tableColAlignFormat, tableColFormat, tableHeaderFormat, tableRowFormat, toHexColor, underlineFormat, unescapeHtml, validateDelta, videoFormat };