postext 1.35.1 → 1.37.0

package/dist/vdt.d.ts

@@ -1,4 +1,4 @@
-import type { ColorPaletteEntry, DocumentMetadata, PostextResource, Resource, ResourceSafeArea, TableCellAlign, TableCellVerticalAlign, ResolvedPageConfig, ResolvedLayoutConfig, ResolvedBodyTextConfig, ResolvedHeadingsConfig, ResolvedTableStyleConfig, ResolvedNamedTableStyleConfig, TableRules, ResolvedCaptionStyleConfig, ResolvedDiagramStyleConfig, ResolvedVideoStyleConfig, ResolvedVideoPlayerOptions, VideoSource, ResolvedParagraphStyleConfig, ResolvedCalloutStyleConfig, ResolvedChipStyleConfig, ResolvedMarkStyleConfig, CalloutSpan, CalloutPlacement, ResolvedUnorderedListsConfig, ResolvedOrderedListsConfig, ResolvedMathConfig, ResolvedPdfGenerationConfig, ResolvedPrintConfig, ResolvedContrastConfig, ResolvedChecksConfig, ResolvedFolioConfig, ResolvedDesignSlot, ResolvedPartsConfig, ResolvedHeadingStyleConfig, ResolvedTocConfig, ResolvedIndexConfig, ResolvedFootnotesConfig, ResolvedCrossRefsConfig, ResolvedCitationsConfig, ResolvedCjkConfig, CjkRegion, PageRole, PartState, PostextConfig, FolioPaperConfig, ResolvedComicsConfig, ResolvedLineNumbersConfig, ResolvedCodeStyleConfig, PageTemplate, ResolvedLabelStyle } from './types';
+import type { ColorPaletteEntry, DocumentMetadata, PostextResource, Resource, ResourceSafeArea, TableCellAlign, TableCellVerticalAlign, ResolvedPageConfig, ResolvedLayoutConfig, ResolvedBodyTextConfig, ResolvedHeadingsConfig, ResolvedTableStyleConfig, ResolvedNamedTableStyleConfig, TableRules, ResolvedCaptionStyleConfig, ResolvedDiagramStyleConfig, ResolvedVideoStyleConfig, ResolvedVideoPlayerOptions, VideoSource, ResolvedParagraphStyleConfig, ResolvedCalloutStyleConfig, ResolvedChipStyleConfig, ResolvedMarkStyleConfig, CalloutSpan, CalloutPlacement, ResolvedUnorderedListsConfig, ResolvedOrderedListsConfig, ResolvedMathConfig, ResolvedPdfGenerationConfig, ResolvedPrintConfig, ResolvedContrastConfig, ResolvedChecksConfig, ResolvedFolioConfig, ResolvedDesignSlot, ResolvedPartsConfig, ResolvedHeadingStyleConfig, ResolvedTocConfig, ResolvedIndexConfig, ResolvedFootnotesConfig, ResolvedCrossRefsConfig, ResolvedCitationsConfig, ResolvedCjkConfig, CjkRegion, PageRole, PartState, PostextConfig, FolioPaperConfig, ResolvedComicsConfig, ResolvedLineNumbersConfig, ResolvedCodeStyleConfig, PageTemplate, ResolvedLabelStyle, Dimension } from './types';
 import type { NumeralStyle } from './numbering';
 import type { MathRender } from './math/types';
 export interface BoundingBox {
@@ -187,6 +187,12 @@ export interface VDTChip {
      *  pass joins the pieces that share a line into one box. Never left on a
      *  chip of a finished line. */
     joinNext?: boolean;
+    /** Where each character of the chip's runs (joined, in logical order)
+     *  stands in the source, counted from the chip's leading `:` (#857): add
+     *  the source offset of the chip's plain character (its block's
+     *  `sourceMap`). Absent when the runs do not read as written (a chip in
+     *  small capitals is still mapped; one cut by direction is not). */
+    sourceOffsets?: number[];
 }
 export interface VDTLineSegment {
     kind: 'text' | 'space' | 'math' | 'swatch' | 'chip';
@@ -1340,6 +1346,71 @@ export interface VDTFigureLabel {
     /** The label's text in the source (absolute offsets). */
     sourceStart: number;
     sourceEnd: number;
+    /** The source offset of each character of `text` (absolute), when the
+     *  text reads as written (#857). */
+    sourceMap?: number[];
+    /** On a composed page, the label's stable id,
+     *  `cp<fence>:<slot>:label:<anchor>` (`@<k>` for the k-th label placed by
+     *  percentages): the same in every locale (#857). */
+    id?: string;
+    /** The anchor it is set at, as `resourceId#anchorId` (#857); absent for
+     *  a label placed by percentages. */
+    anchorRef?: string;
+    /** Where the label is painted: the upright box round its text (and
+     *  background), in the coordinates of the block's own frame (a page's
+     *  flow, or the frame of a composed page its block stands in), stamped
+     *  once the pages exist (#860). `sourceAt` answers a point inside it
+     *  with the label. Absent for a label that is not drawn. */
+    rect?: BoundingBox;
+    /** The label set on the picture (#860): absent when it is not drawn (its
+     *  anchor is unknown, the resource is no picture). */
+    layout?: VDTFigureLabelLayout;
+}
+/**
+ * A figure label laid out on its picture (#860, DESIGN §2.6). Everything is
+ * in the label's own frame: its origin is the anchor's point and its axes
+ * are turned by `rotate` degrees (clockwise) about it. That point is
+ * `(x, y)` px from the top-left corner of the picture's body (the block's
+ * `bodyRect` as drawn, its crop applied), so the label moves with its
+ * block. Painters: `translate(bodyX + x, bodyY + y) · rotate(rotate)`
+ * (`figureLabelMatrix`), then the halo, the background and the lines.
+ */
+export interface VDTFigureLabelLayout {
+    x: number;
+    y: number;
+    /** Degrees, clockwise. Absent = 0. */
+    rotate?: number;
+    /** The text, as caption lines are (segments, chips, marks, bidi order),
+     *  positioned in the label's frame. */
+    lines: VDTLine[];
+    /** The box of the lines in the label's frame. */
+    box: BoundingBox;
+    fontString: string;
+    boldFontString: string;
+    italicFontString: string;
+    boldItalicFontString: string;
+    /** Hex. */
+    color: string;
+    /** The glyphs stroked `2 × widthPx` wide in `color` under the text. */
+    halo?: {
+        color: string;
+        widthPx: number;
+    };
+    /** A fill behind the text: `rect` is the box grown by the style's
+     *  padding. */
+    background?: {
+        color: string;
+        rect: BoundingBox;
+    };
+    /** The scale the label was set at to fit its width (`minScale` at
+     *  least); absent at 1. */
+    scale?: number;
+    /** Still wider than its anchor's width at the style's `minScale`. */
+    overflow?: true;
+    /** The label style it was set in (`labelStyles[].id`). */
+    styleId?: string;
+    /** Set right to left (its text opens with a right-to-left letter). */
+    direction?: 'rtl';
 }
 /**
  * A paragraph's drop cap (#623, {@link VDTBlock.dropCap}), in page
@@ -1472,6 +1543,23 @@ export interface VDTBlock {
     indexLevel?: number;
     /** Id of the heading style (`{style="…"}`) applied to this heading. */
     headingStyleId?: string;
+    /** A heading set in a box or a frame of a composed page whose level or
+     *  heading style has a design of its own (#906): what the design
+     *  (`designOverlay`) is laid out with. Such a heading carries no
+     *  `headingStyleId`, `attrs` or `titleBreaks`: in the flow those open a
+     *  styled section, a chapter's attributes, an opener band or a page's
+     *  role, which a heading inside a box does not. The block is as tall as
+     *  the design needs, as a heading in a column is. */
+    boxDesign?: {
+        styleId?: string;
+        attrs?: Record<string, string>;
+        attrSources?: Record<string, {
+            start: number;
+            end: number;
+        }>;
+        titleBreaks?: number[];
+        titleLength?: number;
+    };
     /** True for a heading whose style has `numbered: false`: it advances no
      *  counter and `{chapterNumber}` is empty on its pages. */
     unnumbered?: boolean;
@@ -1500,10 +1588,12 @@ export interface VDTBlock {
      *  make the row a link to it. The contents keep their own rhythm:
      *  entries and part rows neither snap to the baseline grid nor serve as
      *  column-balancing stretch points. `continued`: a repeated head row (see
-     *  `tocPart`). */
+     *  `tocPart`). `headingSource`: where the heading the entry lists starts
+     *  in its chapter's Markdown body (`OutlineEntry.headingSource`, #857). */
     tocEntry?: {
         pageIndex?: number;
         continued?: true;
+        headingSource?: number;
     };
     numberPrefix?: string;
     /** What joins {@link numberPrefix} to the title
@@ -1836,6 +1926,28 @@ export interface VDTExclusion {
     /** The id of the block that wraps the text: an inline figure's block, a
      *  float's, or a box's frame. */
     ownerId: string;
+    /** A contour wrap (#883): the picture's shape, which sets each line
+     *  beside it short by the shape's width there rather than by
+     *  {@link width}. Absent: the rectangle. */
+    contour?: VDTExclusionContour;
+}
+/** The shape a contour wrap runs round (#883), in page px: bands of the
+ *  page, each with the shape's extent across it, and the margin kept round
+ *  them (across, above and below). A line meets the shape where a band
+ *  lies within the margin of the line's own band. */
+export interface VDTExclusionContour {
+    spans: VDTContourSpan[];
+    margin: number;
+    /** The insets are rounded up to whole multiples of this (px): one body
+     *  character under a CJK character grid, so the lines keep to it. */
+    quantum?: number;
+}
+/** One band of a contour (`VDTExclusionContour.spans`). */
+export interface VDTContourSpan {
+    y: number;
+    height: number;
+    left: number;
+    right: number;
 }
 /** The notes set at the foot of one column (`footnotes.placement:
  *  'column'`). The note paragraphs themselves are in `VDTPage.floats` (and
@@ -1954,7 +2066,23 @@ export interface VDTDesignBoxStyle {
     borderRadiusPx: number;
 }
 /** Text block rendered inside a design slot (header / footer / heading). */
-export interface VDTDesignTextBlock {
+/** Where a design block comes from in the configuration (#857): the
+ *  element of its design slot (`DesignElement.id`) and the JSON pointer of
+ *  that element (`/pageTemplates/0/decoration/elements/2`,
+ *  `/footer/elements/0`). Set on the blocks of a composed page's decoration
+ *  and of the running heads; absent where the slot's origin is not known
+ *  (a heading style's design, a callout's own overlay). */
+export interface VDTDesignBlockOrigin {
+    elementId?: string;
+    configPath?: string;
+    /** The Markdown attribute the block shows: `x` for a text element whose
+     *  content is `{attr.x}` (its `sourceStart`/`sourceEnd` are the value's
+     *  in the page fence or the heading) and for an image whose `resourceId`
+     *  is `{attr.x}`; `label` / `title` for a frame's tab and title (the
+     *  `:::frame` fence's). Absent otherwise. */
+    attr?: string;
+}
+export interface VDTDesignTextBlock extends VDTDesignBlockOrigin {
     kind: 'text';
     bbox: BoundingBox;
     fontString: string;
@@ -2028,7 +2156,7 @@ export interface VDTVerticalText {
     centralBaselines: Record<string, number>;
 }
 /** Rendered rule inside a design slot. */
-export interface VDTDesignRuleBlock {
+export interface VDTDesignRuleBlock extends VDTDesignBlockOrigin {
     kind: 'rule';
     bbox: BoundingBox;
     color: string;
@@ -2036,7 +2164,7 @@ export interface VDTDesignRuleBlock {
     direction: 'horizontal' | 'vertical';
 }
 /** Decorative rounded box. */
-export interface VDTDesignBoxBlock {
+export interface VDTDesignBoxBlock extends VDTDesignBlockOrigin {
     kind: 'box';
     bbox: BoundingBox;
     box: VDTDesignBoxStyle;
@@ -2047,7 +2175,7 @@ export interface VDTDesignBoxBlock {
     clip?: RoundedOutline;
 }
 /** Image drawn from the resource image registry (e.g. a callout icon). */
-export interface VDTDesignImageBlock {
+export interface VDTDesignImageBlock extends VDTDesignBlockOrigin {
     kind: 'image';
     bbox: BoundingBox;
     /** Out-of-band binary id resolved at render time (canvas registry, HTML
@@ -2258,6 +2386,10 @@ export interface ReflowEvent {
     /** The frame whose change caused this event; `'gutter'` when the spine
      *  band of a spread template kept the frame off it (#861). */
     cause?: string;
+    /** `continued` (#859): the page (`VDTPage.index`) the frame's content
+     *  goes on on, and the frame there (`VDTFrame.id`, `cp<n>:<slot>~<k>`). */
+    toPage?: number;
+    toFrame?: string;
 }
 /** One frame of a composed page, in sheet coordinates. Its box and its
  *  content are ordinary callout blocks in `page.floats` (and
@@ -2267,8 +2399,10 @@ export interface ReflowEvent {
  *  turn, and how much of its content did not fit. */
 export interface VDTFrame {
     /** `cp<fenceIndex>:<name>`: the same in every locale and across
-     *  relayouts (`~<n>` is reserved for the n-th continuation piece on a
-     *  later page, #859). */
+     *  relayouts. On the n-th page added by continuation (#859) a frame is
+     *  `cp<fenceIndex>:<name>~<n>`, and the frame that takes content from
+     *  the page before is named by the frame of the fence's own page that
+     *  first sent it on (`cp0:dinero~1`). */
     id: string;
     /** The frame's name in its template (the slot it receives). */
     name: string;
@@ -2296,13 +2430,23 @@ export interface VDTFrame {
     layer: number;
     /** The callout style the frame is drawn with; absent = frameless. */
     styleId?: string;
-    /** Text scale the reflow ladder applied (1 = none; #858). */
+    /** Text scale the reflow ladder applied (1 = none; #858): the frame's
+     *  content is laid out `1 / scale` times as wide and tall as `rect` and
+     *  painted scaled by `scale` about the top-left of `rect`, so its font
+     *  sizes, leading and spacing shrink together. Its blocks' coordinates
+     *  are in that laid-out frame: {@link frameMatrix} (`composed/paint.ts`)
+     *  puts them on the sheet. */
     scale: number;
+    /** Scale the reflow ladder set the pictures of the frame's content at
+     *  (#858), below 1; absent when they keep their size. */
+    imageScale?: number;
     /** Height of content that did not fit in the frame, px (0 = it fits).
      *  Past the frame's foot it is clipped on paged output. */
     overflowPx: number;
-    /** The frame of the same page whose content this one goes on with
-     *  (`next`), and the one this frame's content goes on in. */
+    /** The frame whose content this one goes on with (`next`, or on a page
+     *  added by continuation, #859, the frame of the page before), and the
+     *  one this frame's content goes on in (on this page, or on a page added
+     *  after it). */
     continuedFrom?: string;
     continuesTo?: string;
     /** Ids of the blocks set in this frame (its box first), in
@@ -2353,6 +2497,9 @@ export interface VDTComposedPage {
     };
     /** The page fence's ordinal in its chapter (stable across locales). */
     fenceIndex: number;
+    /** On a page added by continuation (#859): the index (`VDTPage.index`)
+     *  of the fence's own page, whose frames' content goes on here. */
+    continuationOf?: number;
     /** The role the template reports to design slots (`role`, default
      *  `'composed'`). `page.role` is `'composed'` whatever this says. */
     role: string;
@@ -2375,6 +2522,13 @@ export interface VDTComposedPage {
     /** The page fence, opening line to closing fence (absolute offsets). */
     sourceStart: number;
     sourceEnd: number;
+    /** A digest of everything the page's frames were laid out from (#857):
+     *  template, Markdown and blocks, styles, fonts, locale, side and
+     *  geometry. Two pages with the same key hold the same frames (their
+     *  source offsets aside), so a host may keep the pixels it painted for
+     *  one (with the same running heads and decoration). Absent when the
+     *  page reads what the key does not hold (a footnote, a reference). */
+    layoutKey?: string;
 }
 /** A comic page (`:::page`): its panels, the split lines between them and
  *  the lettering, on the sheet. Also the comic of a strip
@@ -2675,6 +2829,56 @@ export interface ConfigWarning {
      *  about, when its owner is one. */
     ownerId?: string;
 }
+/** A step of the reflow ladder (#858, DESIGN §5.4), in ladder order:
+ *  `free` (the frame grows into free space up to its `maxHeight`), `push`
+ *  (its group moves the frames after it and the ones that `shrink` yield),
+ *  `scaleImages` (pictures of the frame and its group, down to
+ *  `fit.imageMinScale`), `redistribute` (the other frames of its group go
+ *  down to their minimum or their content, a row's give width),
+ *  `shrinkText` (down to `fit.minScale`), `continue` (`overflow.continueIn`
+ *  to another page, #859). */
+export type FrameFitStep = 'free' | 'push' | 'scaleImages' | 'redistribute' | 'shrinkText' | 'continue';
+/** A change that would make a frame's content fit (#858): data, so the
+ *  Sandbox can offer it as a confirmed edit. `path` is the JSON pointer of
+ *  the config value to set to `value`; a Markdown change carries the
+ *  source range it is about instead. Values are worked out from the
+ *  shortfall: `allowShrink` the largest text scale (in 2.5 % steps) at
+ *  which the content fits (`also`: the switch to turn on with it),
+ *  `raiseMax` / `lowerMin` the height in whole millimetres, `useTemplate`
+ *  another template of the book with a frame of this name in which the
+ *  content fits, `shortenText` about how many characters to cut. */
+export type FrameOverflowProposal = {
+    kind: 'allowShrink';
+    path: string;
+    value: number;
+    also?: {
+        path: string;
+        value: boolean;
+    }[];
+} | {
+    kind: 'raiseMax';
+    path: string;
+    value: Dimension;
+} | {
+    kind: 'lowerMin';
+    path: string;
+    value: Dimension;
+    frame: string;
+} | {
+    kind: 'continueNextPage';
+    path: string;
+    value: 'next-page';
+} | {
+    kind: 'useTemplate';
+    value: string;
+    sourceStart?: number;
+    sourceEnd?: number;
+} | {
+    kind: 'shortenText';
+    value: number;
+    sourceStart?: number;
+    sourceEnd?: number;
+};
 /** The kinds of {@link ConfigWarning} a page template gives (#853). */
 export type PageTemplateWarningKind = 'templateDuplicate' | 'templateExtendsCycle' | 'templateExtendsUnknown' | 'frameDuplicate' | 'frameStyleUnknown' | 'frameAnchorUnknown' | 'frameMinMax' | 'groupFrameUnknown' | 'groupFrameTwice' | 'frameChainLoop' | 'overflowTargetUnknown' | 'labelStyleUnknown';
 /** Where a content warning points: the source range of the construct in
@@ -2778,11 +2982,12 @@ export type ContentWarning = ContentWarningBase & (
 }
 /** Content of a composed page names a slot (`slot="…"`,
  *  `:::frame{slot=…}`) that is no frame of the page's template: it goes
- *  to the template's flow frame. */
+ *  to the template's flow frame (`frame`, when the template has one). */
  | {
     kind: 'slotUnknown';
     template: string;
     slot: string;
+    frame?: string;
     fenceIndex: number;
 }
 /** A frame of a composed page's template receives no content: nothing
@@ -2813,6 +3018,32 @@ export type ContentWarning = ContentWarningBase & (
     fenceIndex: number;
     overflowMm: number;
     configPath: string;
+    /** The document's locale (`config.locale`): the same page overflows in
+     *  one language and fits in another. */
+    locale?: string;
+    /** The steps of the reflow ladder (#858) that applied to the frame, in
+     *  the order they were tried; none made the content fit. */
+    stepsTried: FrameFitStep[];
+    /** The text scale the frame was left at (1 = none). */
+    scale: number;
+    /** The scale its pictures were left at, below 1. */
+    imageScale?: number;
+    /** Changes that would make the content fit, with their values worked
+     *  out from the shortfall (each tried on the page where it can be). */
+    proposals: FrameOverflowProposal[];
+}
+/** A frame's content went on to other pages (#859) as many times as a
+ *  composed page may add (`pages`, 16) and still does not fit: what is
+ *  left is cut at the foot of the frame on the last page added
+ *  (`overflowMm`, `pageIndex`). */
+ | {
+    kind: 'frameContinuationLimit';
+    template: string;
+    frame: string;
+    fenceIndex: number;
+    pages: number;
+    overflowMm: number;
+    configPath: string;
 }
 /** A composed page's fence and its template disagree about spreads
  *  (#861): `::::page{template spread}` names a template that is a single
@@ -2827,6 +3058,29 @@ export type ContentWarning = ContentWarningBase & (
     fence: boolean;
     templateSpread: boolean;
 }
+/** A `::label[…]{at="…"}` of a `:::figure` (#860) names an anchor its
+ *  resource does not have: the label is not drawn (the reflowable
+ *  output still lists it). `known` lists the resource's anchor ids. The
+ *  source range is the label's text. */
+ | {
+    kind: 'labelAnchorUnknown';
+    resourceId: string;
+    anchor: string;
+    known: string[];
+    locale?: string;
+    labelId?: string;
+}
+/** An anchor of a figure's resource names a label `style` but no
+ *  `::label` of the figure stands at it in this locale (#860): a note,
+ *  the map lacks that word in this edition. The source range is the
+ *  figure's. */
+ | {
+    kind: 'anchorUnlabelled';
+    resourceId: string;
+    anchor: string;
+    style: string;
+    locale?: string;
+}
 /** A `:::paper{…}` attribute the engine cannot read: an unknown key, a
  *  stock, finish or texture it does not know, a number out of range, a
  *  shade that is neither a hex colour nor a palette id, a `showThrough`
@@ -3192,6 +3446,22 @@ export type ContentWarning = ContentWarningBase & (
     scale: number;
     overflowPx?: number;
 }
+/** `pictureBelowPrintSize` (#901): a bitmap with a print size (its own
+ *  `bitmap.resolution`, or a number in `layout.bitmapResolution`) set in
+ *  a column that holds it at under half of it, on a page whose text
+ *  block is wider than that column: `scale` is the share of its print
+ *  width it keeps, `printWidthPx` that width, `widthPx` the column's and
+ *  `pageWidthPx` the text block's. A picture in the flow is never wider
+ *  than its column, and the default page has two (`layout.layoutType:
+ *  'double'`). Found by the layout; reported once per picture. */
+ | {
+    kind: 'pictureBelowPrintSize';
+    resourceId: string;
+    scale: number;
+    printWidthPx: number;
+    widthPx: number;
+    pageWidthPx: number;
+}
 /** `textWrap` (#627): a resource or a box set to wrap text round it
  *  (`placement.wrap`, a box's `wrap`) that does not as asked.
  *  `'tooNarrow'`: the text beside it would be narrower than
@@ -3200,11 +3470,16 @@ export type ContentWarning = ContentWarningBase & (
  *  its band whole; `'moved'`: an inline one was too tall for the room
  *  left in its column and moved on to the next, its anchor with it;
  *  `'verticalText'`: text wraps in horizontal text only, so in a
- *  vertical flow it takes its band whole. `resourceId` names a
- *  resource, `box` a box's style. Found by the layout. */
+ *  vertical flow it takes its band whole; `'noContour'` (#883): a
+ *  contour wrap (`wrap: 'contour'`, or a pushing frame's) round a
+ *  picture whose shape is not known (an SVG with no
+ *  `contour.points`, a bitmap with no transparency, or whose alpha
+ *  channel the host did not trace), so the text runs round its box.
+ *  `resourceId` names a resource, `box` a box's style. Found by the
+ *  layout. */
  | {
     kind: 'textWrap';
-    reason: 'tooNarrow' | 'fewLines' | 'moved' | 'verticalText';
+    reason: 'tooNarrow' | 'fewLines' | 'moved' | 'verticalText' | 'noContour';
     resourceId?: string;
     box?: string;
 }