@scrider/formatter 1.10.1 → 1.10.4

package/dist/index.d.ts

@@ -2,13 +2,55 @@ import { AttributeMap, Op, Delta, InsertOp } from '@scrider/delta';
 export * from '@scrider/delta';
 export { InsertOp as ContentOp } from '@scrider/delta';
 
+/**
+ * Simple Table HTML presentation options for deltaToHtml (clipboard, export).
+ * Structural data stays in Delta (table-row, table-col-align); this only affects inline styles.
+ */
+/** Column/cell horizontal alignment (GFM subset). */
+type TableCellAlign = 'left' | 'center' | 'right';
+/** Optional styling when serializing Simple Tables to HTML. */
+interface TablePresentation {
+    /** Full 1px border on all cell sides. When true, `line` is ignored. */
+    grid?: boolean;
+    /** Bottom border only (DeepSeek / ChatGPT). Used when `grid` is not true. */
+    line?: boolean;
+    /** Border color as explicit hex (e.g. `#e7e7e7`). */
+    borderColor?: string;
+    /** Background on header cells (`th`). */
+    headerShade?: boolean;
+    /** Background on even table rows in the body (see `isZebraBodyRow`). */
+    zebraRows?: boolean;
+    /** `font-weight: bold` on `th`. */
+    headerBold?: boolean;
+    /** `text-align: center` on `th` (GitHub-style header). */
+    headerCenter?: boolean;
+    /**
+     * Alignment for cells without `table-col-align` in Delta. Never overrides GFM column align.
+     * @default 'left'
+     */
+    defaultCellAlign?: TableCellAlign;
+}
+interface ResolvedTablePresentation {
+    grid: boolean;
+    line: boolean;
+    borderColor: string;
+    headerShade: boolean;
+    zebraRows: boolean;
+    headerBold: boolean;
+    headerCenter: boolean;
+    defaultCellAlign: TableCellAlign;
+}
+declare function resolveTablePresentation(presentation?: TablePresentation): ResolvedTablePresentation;
+/** Match CSS `tr:nth-child(even) td` when header rows precede body in `<table>`. */
+declare function isZebraBodyRow(headerRowCount: number, bodyRowIndex: number): boolean;
+
 /**
  * Document-level metadata (Scrider format extension).
  *
  * Concrete schema for the opaque `scrider-metadata` sibling field defined in
  * `@scrider/delta` (`ScriderDocument`). It carries document-wide defaults ONCE
- * (line spacing, paragraph spacing, indent, heading policy, fonts) instead of
- * duplicating them as block attributes on every `\n`.
+ * (line spacing, paragraph spacing, indent, heading policy, fonts, table
+ * presentation) instead of duplicating them as block attributes on every `\n`.
  *
  * Layering:
  * - `@scrider/delta` treats the value as opaque `Record<string, unknown>` — it
@@ -18,11 +60,15 @@ export { InsertOp as ContentOp } from '@scrider/delta';
  *   export projection).
  *
  * All fields are optional and additive: extending the interface never changes the
- * op-stream and is backward compatible. Presentation-relevant fields are projected
- * to HTML via {@link documentMetadataToPresentation}; heading/font policy is applied
- * by upstream layers (CSS vars, bake) and is intentionally NOT part of the inline
- * export projection.
+ * op-stream and is backward compatible.
+ *
+ * Projection:
+ * - Spacing / indent → {@link documentMetadataToPresentation} (paragraph CSS).
+ * - Heading policy → {@link resolveHeadingPolicy} / heading block styles on `h1`–`h6`.
+ * - `tablePresentation` → same shape as `DeltaToHtmlOptions.tablePresentation`
+ *   (used when the explicit option is omitted).
  */
+
 interface ScriderDocumentMetadata {
     /** Line spacing multiplier, e.g. `1.5`. */
     lineSpacing?: number;
@@ -34,16 +80,35 @@ interface ScriderDocumentMetadata {
     textIndentCm?: number;
     /** Extra left indent in cm on top-level `<ul>`/`<ol>` (shifts marker + text). */
     listBlockIndentCm?: number;
-    /** Document heading horizontal alignment policy. */
+    /** Document heading horizontal alignment policy. Presence = policy on. */
     headingAlign?: 'left' | 'center' | 'right';
-    /** Document heading bold policy. */
+    /** Document heading bold policy. `true` = force bold on `h1`–`h6`. */
     headingBold?: boolean;
-    /** Named heading size-grid preset id (schema defined upstream). */
+    /**
+     * Named heading size-grid preset id (`scrider` | `google` | `word` | `browser` | `githubEm`).
+     * Ignored when {@link headingAuto} is true.
+     */
     headingSizeGridPreset?: string;
+    /**
+     * When true, headings use browser/CSS natural size (no size-grid projection).
+     * Mutually exclusive with {@link headingSizeGridPreset} in Settings UI.
+     */
+    headingAuto?: boolean;
+    /**
+     * Heading decoration preset (`none` | `scrider` | `github`).
+     * Editor: `data-scrider-heading-decoration`. Export: PDF/HTML vertical rhythm + rules.
+     */
+    headingDecoration?: 'none' | 'scrider' | 'github';
     /** Default document font family (bare family name, e.g. `Georgia`). */
     defaultFont?: string;
     /** Default document font size as a CSS length, e.g. `12pt`. */
     defaultFontSize?: string;
+    /**
+     * Simple / view table chrome (borders, header shade, zebra). Same shape as
+     * `DeltaToHtmlOptions.tablePresentation`. Persisted with the document so export
+     * matches Settings without a separate channel.
+     */
+    tablePresentation?: TablePresentation;
 }
 
 /**
@@ -201,11 +266,21 @@ interface EmbedIsolationOptions {
     /** Add `allow="…; cross-origin-isolated"` on codeWidget iframes. @default false */
     crossOriginIsolated?: boolean;
 }
+/**
+ * Host-provided share→embed URL transform for `{ codeWidget }` (arch-set1 D2).
+ * When omitted, the stored URL is used as-is (passthrough).
+ */
+type CodeWidgetEmbedUrlFn = (url: string) => string;
 /**
  * Optional context passed to Format.render() during conversion.
  */
 interface FormatRenderContext {
     embed?: EmbedIsolationOptions;
+    /**
+     * Optional share→embed URL transform for codeWidget iframes.
+     * Integration policy lives in the host (editor/demo), not the formatter.
+     */
+    codeWidgetEmbedUrl?: CodeWidgetEmbedUrlFn;
 }
 /**
  * Result returned by Format.match() when an HTML element is recognized.
@@ -1122,9 +1197,9 @@ declare const blockFormat: Format<Record<string, unknown>>;
  * embeds can boot SharedArrayBuffer when the host is cross-origin-isolated.
  * `credentialless` keeps the frame loadable under COEP on such a host.
  *
- * The src is run through `toCodeWidgetEmbedUrl` at render time, which is
- * idempotent, so resize/float attributes and the Delta ↔ HTML round-trip stay
- * stable regardless of whether the stored value is the user URL or embed URL.
+ * Share→embed URL rules are **not** in the formatter (arch-set1 D2). Inject
+ * `deltaToHtml({ codeWidgetEmbedUrl })` / `FormatRenderContext.codeWidgetEmbedUrl`
+ * from the host; default is passthrough of the stored URL.
  */
 declare const codeWidgetFormat: Format<string>;
 
@@ -1504,13 +1579,12 @@ interface ResolvedDocumentPresentation {
 declare function resolveDocumentPresentation(presentation?: DocumentPresentation): ResolvedDocumentPresentation | undefined;
 /**
  * Project {@link ScriderDocumentMetadata} onto an HTML {@link DocumentPresentation}
- * (export / clipboard inline CSS).
+ * (export / clipboard inline CSS for paragraphs/lists).
  *
- * Only presentation-relevant fields are mapped (line/paragraph spacing, indent).
- * Heading policy (align/bold/size grid) and fonts are applied by upstream layers
- * (CSS vars in the editor, bake into block/inline attrs) and are deliberately not
- * part of the inline projection. Returns `undefined` when nothing maps, so callers
- * can fall back cleanly.
+ * Maps line/paragraph spacing and indent only. Heading policy is projected
+ * separately via {@link resolveHeadingPolicy} / {@link headingPolicyStyleParts}
+ * onto `h1`–`h6`. `tablePresentation` is read from metadata in `deltaToHtml`
+ * when the explicit option is omitted. Returns `undefined` when nothing maps.
  */
 declare function documentMetadataToPresentation(metadata: ScriderDocumentMetadata | undefined): DocumentPresentation | undefined;
 /**
@@ -1532,46 +1606,32 @@ declare function documentPresentationStyleParts(tag: string, resolved: ResolvedD
 declare function blockPresentationStyleParts(tag: string, blockAttributes: AttributeMap | undefined, resolved: ResolvedDocumentPresentation | undefined): string[];
 
 /**
- * Simple Table HTML presentation options for deltaToHtml (clipboard, export).
- * Structural data stays in Delta (table-row, table-col-align); this only affects inline styles.
+ * Document-level heading policy projected to export HTML (`h1`–`h6` inline CSS).
+ *
+ * Editor applies the same policy via CSS vars (`--scrider-heading-*`, `--scrider-hN-size`).
+ * Size maps mirror `editor-core` `HEADER_SIZE_PRESETS` — keep in sync.
  */
-/** Column/cell horizontal alignment (GFM subset). */
-type TableCellAlign = 'left' | 'center' | 'right';
-/** Optional styling when serializing Simple Tables to HTML. */
-interface TablePresentation {
-    /** Full 1px border on all cell sides. When true, `line` is ignored. */
-    grid?: boolean;
-    /** Bottom border only (DeepSeek / ChatGPT). Used when `grid` is not true. */
-    line?: boolean;
-    /** Border color as explicit hex (e.g. `#e7e7e7`). */
-    borderColor?: string;
-    /** Background on header cells (`th`). */
-    headerShade?: boolean;
-    /** Background on even table rows in the body (see `isZebraBodyRow`). */
-    zebraRows?: boolean;
-    /** `font-weight: bold` on `th`. */
-    headerBold?: boolean;
-    /** `text-align: center` on `th` (GitHub-style header). */
-    headerCenter?: boolean;
-    /**
-     * Alignment for cells without `table-col-align` in Delta. Never overrides GFM column align.
-     * @default 'left'
-     */
-    defaultCellAlign?: TableCellAlign;
-}
-interface ResolvedTablePresentation {
-    grid: boolean;
-    line: boolean;
-    borderColor: string;
-    headerShade: boolean;
-    zebraRows: boolean;
-    headerBold: boolean;
-    headerCenter: boolean;
-    defaultCellAlign: TableCellAlign;
+
+type HeaderLevel = 1 | 2 | 3 | 4 | 5 | 6;
+type HeaderSizeMap = Readonly<Record<HeaderLevel, string>>;
+type HeaderSizePresetName = 'scrider' | 'google' | 'word' | 'browser' | 'githubEm';
+/** Keep in sync with `@scrider/editor-core` `HEADER_SIZE_PRESETS`. */
+declare const HEADER_SIZE_PRESETS: Readonly<Record<HeaderSizePresetName, HeaderSizeMap>>;
+interface ResolvedHeadingPolicy {
+    align: 'left' | 'center' | 'right' | undefined;
+    bold: boolean;
+    /** When set and `auto` is false, emit font-size on `hN` when Delta has no inline size. */
+    sizePreset: HeaderSizePresetName | undefined;
+    auto: boolean;
 }
-declare function resolveTablePresentation(presentation?: TablePresentation): ResolvedTablePresentation;
-/** Match CSS `tr:nth-child(even) td` when header rows precede body in `<table>`. */
-declare function isZebraBodyRow(headerRowCount: number, bodyRowIndex: number): boolean;
+declare function resolveHeadingPolicy(metadata: ScriderDocumentMetadata | undefined): ResolvedHeadingPolicy | undefined;
+/**
+ * Inline styles for a heading block from document metadata.
+ * Baked Delta attrs win: `align` on `\n` skips metadata align; presence of any
+ * text with explicit `size` is not detectable at block level — size from preset
+ * is always emitted when policy is on (matches editor CSS vars on `hN`).
+ */
+declare function headingPolicyStyleParts(tag: string, blockAttributes: AttributeMap | undefined, policy: ResolvedHeadingPolicy | undefined): string[];
 
 /**
  * Delta → HTML Conversion
@@ -1645,10 +1705,12 @@ interface DeltaToHtmlOptions {
     /**
      * Document-level metadata (Scrider format extension, `scrider-metadata`).
      *
-     * When {@link documentPresentation} is not provided, the presentation-relevant
-     * fields of this metadata are projected to inline CSS via
-     * `documentMetadataToPresentation` (export/clipboard). An explicit
-     * `documentPresentation` always takes precedence. Does not change Delta.
+     * When {@link documentPresentation} is not provided, spacing/indent fields are
+     * projected via `documentMetadataToPresentation`. Heading policy
+     * (`headingAlign` / `headingBold` / `headingSizeGridPreset` / `headingAuto`)
+     * is projected onto `h1`–`h6`. When {@link tablePresentation} is omitted,
+     * `metadata.tablePresentation` is used. An explicit `documentPresentation` /
+     * `tablePresentation` always takes precedence. Does not change Delta.
      */
     documentMetadata?: ScriderDocumentMetadata;
     /**
@@ -1657,6 +1719,12 @@ interface DeltaToHtmlOptions {
      * Enable when the host page is cross-origin-isolated (COOP + COEP).
      */
     embed?: EmbedIsolationOptions;
+    /**
+     * Share→embed URL transform for `{ codeWidget }` iframes (arch-set1 D2).
+     * Default: passthrough (stored URL unchanged). Provider rules belong in the
+     * host — inject e.g. `@scrider/editor-react`'s `toCodeWidgetEmbedUrl`.
+     */
+    codeWidgetEmbedUrl?: CodeWidgetEmbedUrlFn;
 }
 /**
  * Convert a Delta to an HTML string
@@ -1795,25 +1863,14 @@ declare function escapeHtml(text: string): string;
  */
 declare function unescapeHtml(text: string): string;
 /**
- * Convert a code-playground URL to an embeddable iframe URL (Phase 8 Part 3.5).
- *
- * Idempotent: a URL that is already in embed form is returned unchanged, so the
- * Delta → HTML → Delta round-trip is stable regardless of which form is stored.
- *
- *   Provider     | User URL                         | Embed URL
- *   -------------|----------------------------------|-----------------------------------
- *   StackBlitz   | stackblitz.com/edit/{id}         | …?embed=1
- *                | stackblitz.com/github/{u}/{r}    | …?embed=1
- *   CodeSandbox  | codesandbox.io/s/{id}            | codesandbox.io/embed/{id}
- *   Replit       | replit.com/@{u}/{repl}           | …?embed=true
- *   CodePen      | codepen.io/{u}/pen/{id}          | codepen.io/{u}/embed/{id}
- *   JSFiddle     | jsfiddle.net/{u}/{id}/           | jsfiddle.net/{u}/{id}/embedded/
- *   Trinket      | trinket.io/{lang}/{id}           | trinket.io/embed/{lang}/{id}
- *   OneCompiler  | onecompiler.com/{lang}/{id}      | onecompiler.com/embed/{lang}/{id}
- *
- * Unknown hosts are returned unchanged (the marker `data-code-widget` still
- * makes them render as an iframe; auto-detection of bare URLs lives in the
- * editor layer).
+ * Resolve codeWidget iframe `src` (arch-set1 D2).
+ * Uses the host-injected transform when present; otherwise passthrough.
+ */
+declare function resolveCodeWidgetEmbedSrc(url: string, context?: FormatRenderContext): string;
+/**
+ * @deprecated Since 1.10.4 — identity/passthrough only. Provider share→embed
+ * rules live in the host (`deltaToHtml({ codeWidgetEmbedUrl })` / editor-react
+ * `toCodeWidgetEmbedUrl`). Kept as a stable export name for old imports.
  */
 declare function toCodeWidgetEmbedUrl(url: string): string;
 
@@ -1942,6 +1999,11 @@ interface DeltaToMarkdownOptions {
      * `render()` is used as HTML fallback in Markdown.
      */
     registry?: Registry;
+    /**
+     * Share→embed URL transform for attributed `{ codeWidget }` HTML fallback
+     * (arch-set1 D2). Default: passthrough.
+     */
+    codeWidgetEmbedUrl?: CodeWidgetEmbedUrlFn;
     /**
      * Rendering style for `{ softBreak: true }` embeds (Phase 7 Part 0).
      *
@@ -2204,4 +2266,4 @@ declare function collectAdjacentTableLines<T extends {
  */
 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 CellHorizontalAlign, type CellVerticalAlign, type ColumnsBlockData, type DOMAdapter, type DOMDocument, type DOMDocumentFragment, type DOMElement, type DOMNode, type DOMNodeList, type DeltaToHtmlOptions, type DeltaToMarkdownOptions, type DocumentPresentation, type EmbedIsolationOptions, type FootnotesBlockData, type Format, type FormatDefinition, type FormatMatchResult, type FormatRenderContext, type FormatScope, type HtmlToDeltaOptions, LINE_HEIGHT_BLOCK_TAGS, type ListType, type MarkdownToDeltaOptions, NODE_TYPE, NodeDOMAdapter, PARAGRAPH_SPACING_BLOCK_TAGS, Registry, type RenderProfile, type ResolvedDocumentPresentation, type ResolvedTablePresentation, SCRIDER_LINE_HEIGHT_KEY, SCRIDER_MARGIN_AFTER_KEY, SCRIDER_MARGIN_BEFORE_KEY, SCRIDER_TEXT_INDENT_KEY, type SanitizeOptions, type ScriderDocumentMetadata, TEXT_INDENT_BLOCK_TAGS, type TableBlockData, type TableBlockFloat, type TableCellAlign, type TableCellCoords, type TableColAlignType, type TablePresentation, type TableRegion, alertBlockHandler, alignFormat, backgroundFormat, blockFormat, blockLineHeightStyleParts, blockMarginAfterStyleParts, blockMarginBeforeStyleParts, blockParagraphMarginStyleParts, blockPresentationStyleParts, blockTextIndentStyleParts, blockquoteFormat, boldFormat, boxBlockHandler, browserAdapter, cloneDelta, codeBlockFormat, codeFormat, codeWidgetFormat, collectAdjacentTableLines, colorFormat, columnsBlockHandler, createDefaultBlockHandlers, createDefaultRegistry, defaultBlockFormats, defaultEmbedFormats, defaultFormats, defaultInlineFormats, deltaToDom, deltaToHtml, deltaToMarkdown, dividerFormat, documentMetadataToPresentation, documentPresentationStyleParts, escapeHtml, extractBoxOpAttributes, extractTableRegion, fontFormat, footnoteRefFormat, footnotesBlockHandler, formulaFormat, getAdapter, getNamedColors, headerFormat, headerIdFormat, htmlToDelta, imageFormat, indentFormat, isAdapterAvailable, isAdjacentSimpleTableGridBoundary, isElement, isRemarkAvailable, isTableNewlineOp, isTextNode, isValidColor, isValidHexColor, isZebraBodyRow, italicFormat, kbdFormat, linkFormat, listFormat, markFormat, markdownToDelta, markdownToDeltaSync, nodeAdapter, normalizeDelta, parseScriderLineHeightMultiplier, parseScriderMarginAfterEm, parseScriderMarginBeforeEm, parseScriderMarginEm, preloadRemark, renderDelta, resolveDocumentPresentation, resolveTablePresentation, sanitizeDelta, sizeFormat, slugify, slugifyWithDedup, softBreakFormat, strikeFormat, subscriptFormat, superscriptFormat, tableBlockHandler, tableCellCoordsFromAttributes, tableCellCoordsFromOp, tableColAlignFormat, tableColFormat, tableHeaderFormat, tableRowFormat, toCodeWidgetEmbedUrl, toHexColor, underlineFormat, unescapeHtml, validateDelta, videoFormat };
+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 CellHorizontalAlign, type CellVerticalAlign, type CodeWidgetEmbedUrlFn, type ColumnsBlockData, type DOMAdapter, type DOMDocument, type DOMDocumentFragment, type DOMElement, type DOMNode, type DOMNodeList, type DeltaToHtmlOptions, type DeltaToMarkdownOptions, type DocumentPresentation, type EmbedIsolationOptions, type FootnotesBlockData, type Format, type FormatDefinition, type FormatMatchResult, type FormatRenderContext, type FormatScope, HEADER_SIZE_PRESETS, type HtmlToDeltaOptions, LINE_HEIGHT_BLOCK_TAGS, type ListType, type MarkdownToDeltaOptions, NODE_TYPE, NodeDOMAdapter, PARAGRAPH_SPACING_BLOCK_TAGS, Registry, type RenderProfile, type ResolvedDocumentPresentation, type ResolvedTablePresentation, SCRIDER_LINE_HEIGHT_KEY, SCRIDER_MARGIN_AFTER_KEY, SCRIDER_MARGIN_BEFORE_KEY, SCRIDER_TEXT_INDENT_KEY, type SanitizeOptions, type ScriderDocumentMetadata, TEXT_INDENT_BLOCK_TAGS, type TableBlockData, type TableBlockFloat, type TableCellAlign, type TableCellCoords, type TableColAlignType, type TablePresentation, type TableRegion, alertBlockHandler, alignFormat, backgroundFormat, blockFormat, blockLineHeightStyleParts, blockMarginAfterStyleParts, blockMarginBeforeStyleParts, blockParagraphMarginStyleParts, blockPresentationStyleParts, blockTextIndentStyleParts, blockquoteFormat, boldFormat, boxBlockHandler, browserAdapter, cloneDelta, codeBlockFormat, codeFormat, codeWidgetFormat, collectAdjacentTableLines, colorFormat, columnsBlockHandler, createDefaultBlockHandlers, createDefaultRegistry, defaultBlockFormats, defaultEmbedFormats, defaultFormats, defaultInlineFormats, deltaToDom, deltaToHtml, deltaToMarkdown, dividerFormat, documentMetadataToPresentation, documentPresentationStyleParts, escapeHtml, extractBoxOpAttributes, extractTableRegion, fontFormat, footnoteRefFormat, footnotesBlockHandler, formulaFormat, getAdapter, getNamedColors, headerFormat, headerIdFormat, headingPolicyStyleParts, htmlToDelta, imageFormat, indentFormat, isAdapterAvailable, isAdjacentSimpleTableGridBoundary, isElement, isRemarkAvailable, isTableNewlineOp, isTextNode, isValidColor, isValidHexColor, isZebraBodyRow, italicFormat, kbdFormat, linkFormat, listFormat, markFormat, markdownToDelta, markdownToDeltaSync, nodeAdapter, normalizeDelta, parseScriderLineHeightMultiplier, parseScriderMarginAfterEm, parseScriderMarginBeforeEm, parseScriderMarginEm, preloadRemark, renderDelta, resolveCodeWidgetEmbedSrc, resolveDocumentPresentation, resolveHeadingPolicy, resolveTablePresentation, sanitizeDelta, sizeFormat, slugify, slugifyWithDedup, softBreakFormat, strikeFormat, subscriptFormat, superscriptFormat, tableBlockHandler, tableCellCoordsFromAttributes, tableCellCoordsFromOp, tableColAlignFormat, tableColFormat, tableHeaderFormat, tableRowFormat, toCodeWidgetEmbedUrl, toHexColor, underlineFormat, unescapeHtml, validateDelta, videoFormat };