render-svg

re-exported from @pptx-studio/paint

type RenderErrorCode =
/** `a:prstGeom/@prst` is not one of the 187 `ST_ShapeType` values. */
'RENDER_UNKNOWN_PRESET' |
/** A group tree nests deeper than `MAX_GROUP_DEPTH`. Hostile input. */
'RENDER_GROUP_DEPTH' |
/** The host handed `mount` something that is not an element. */
'RENDER_NO_HOST' |
/** An `a:bodyPr` attribute that is not a length or an angle. */
'RENDER_TEXT_FRAME' |
/** A text direction this package lays out but does not yet draw. */
'RENDER_TEXT_UNSUPPORTED' |
/** An image whose header is not a PNG, JPEG, GIF or BMP. */
'RENDER_IMAGE_FORMAT' |
/** A `devicePixelRatio` that is not a positive number, or one given with no width. */
'RENDER_DEVICE_PIXEL_RATIO';

const RENDER_ERROR_CODES: readonly RenderErrorCode[];

class RenderError extends Error {
  readonly code: RenderErrorCode;
  /** Whatever names the thing that went wrong: a shape name, a preset, a host. */
  readonly subject: string | undefined;
  constructor(code: RenderErrorCode, message: string, subject?: string);
}

function isRenderError(value: unknown): value is RenderError;

const EMU_PER_POINT = 12700;

const ANGLE_UNITS_PER_DEGREE = 60000;

interface Box {
  readonly x: number;
  readonly y: number;
  readonly cx: number;
  readonly cy: number;
}

interface Frame extends Box {
  /** Degrees, clockwise on screen. Normalised to `[0, 360)`. */
  readonly rot: number;
  readonly flipH: boolean;
  readonly flipV: boolean;
}

const IDENTITY_FRAME: Frame;

function frameOf(xfrm: Xfrm): Frame;

interface ChildSpace {
  readonly sx: number;
  readonly sy: number;
  readonly ox: number;
  readonly oy: number;
}

const UNIT_CHILD_SPACE: ChildSpace;

function childSpace(frame: Box, xfrm: Xfrm): ChildSpace;

function swapsExtents(degrees: number): boolean;

function composeTurn(outer: {
  rot: number;
  flipH: boolean;
  flipV: boolean;
}, inner: {
  rot: number;
  flipH: boolean;
  flipV: boolean;
}): {
  rot: number;
  flipH: boolean;
  flipV: boolean;
};

function turnVector(turn: {
  rot: number;
  flipH: boolean;
  flipV: boolean;
}, x: number, y: number): {
  x: number;
  y: number;
};

function placeChild(group: Frame, space: ChildSpace, child: Frame): Frame;

function frameTransform(frame: Frame): string;

interface Vec {
  readonly x: number;
  readonly y: number;
}

function framePoint(frame: Frame, point: Vec): Vec;

function inverseFramePoint(frame: Frame, point: Vec): Vec;

function unionBox(a: Box | null, b: Box | null): Box | null;

interface Placed {
  readonly shape: Shape;
  readonly sheet: Sheet;
  readonly frame: Frame;
  /**
   * The outline, evaluated at the frame's extent.
   *
   * `null` for a shape that declares no geometry and inherits none - a group, a
   * `p:graphicFrame`, or a text box that is nothing but its text.
   */
  readonly geometry: ResolvedGeometry | null;
  /**
   * The definition `geometry` was evaluated from, and the adjust values in
   * force.
   *
   * `geometry` is the answer at one size; this is what produced it. The adjust
   * handles need the definition itself - `resolveHandles` and `dragHandle` both
   * take a `Geometry` - and re-deriving it in the overlay would mean redoing the
   * inheritance walk somewhere that cannot see the sheet chain.
   */
  readonly geometrySource: GeometrySource | null;
  readonly appearance: ResolvedAppearance;
  /** What is painted, after `a:grpFill` has been followed. `null` paints nothing. */
  readonly fill: Fill | null;
  /** The colour `phClr` takes inside `fill`. */
  readonly fillPhClr: Rgba | null;
  /**
   * The rectangle the fill is laid out over, in slide EMU.
   *
   * The shape's own frame, except for an `a:grpFill`, where it is the content
   * bounds of the group the fill came from.
   */
  readonly fillBox: Box;
  readonly colorContext: ColorContext;
  readonly children: readonly Placed[];
  /** For a group: the bounding box of every leaf inside it. `null` otherwise. */
  readonly contentBounds: Box | null;
}

interface GeometrySource {
  readonly geometry: Geometry;
  readonly adjust: readonly PresetGuide[];
}

const MAX_GROUP_DEPTH = 64;

function layoutSheet(sheet: Sheet): readonly Placed[];

function inheritedSheets(sheet: Sheet): readonly Sheet[];

function layoutSlide(sheet: Sheet): readonly Placed[];

function flatten(placed: readonly Placed[]): readonly Placed[];

type AttributeValue = string | number | null | undefined;

interface SvgElement {
  readonly kind: 'element';
  readonly tag: string;
  readonly attrs: Readonly<Record<string, AttributeValue>>;
  readonly children: readonly SvgNode[];
}

interface SvgText {
  readonly kind: 'text';
  readonly text: string;
}

type SvgNode = SvgElement | SvgText;

function element(tag: string, attrs?: Readonly<Record<string, AttributeValue>>, children?: readonly SvgNode[]): SvgElement;

function text(value: string): SvgText;

function num(value: number, precision?: number): string;

function escapeXml(value: string): string;

function serializeSvg(node: SvgNode): string;

const DEFAULT_UNIT = 12700;

const LOCUS_SAMPLES = 25;

const PATH_COLORS: readonly string[];

interface OverlayOptions {
  /** EMU per screen pixel, so chrome stays one thickness at any zoom. */
  readonly unit?: number;
  readonly paths?: boolean;
  readonly textRect?: boolean;
  readonly connectionSites?: boolean;
  readonly handles?: boolean;
  /** Sample each handle axis across its range and draw the curve. Default true. */
  readonly locus?: boolean;
}

interface OverlayGuide {
  readonly name: string;
  readonly value: number;
  /** True for one of the 44 seeded built-ins rather than the shape's own. */
  readonly builtin: boolean;
  readonly finite: boolean;
}

interface OverlayHandle {
  readonly index: number;
  readonly handle: PresetAdjustHandle;
  readonly resolved: ResolvedHandle;
  /** The curve `resolved.pos` traces as each axis sweeps its range, in shape space. */
  readonly locus: readonly (readonly Point[])[];
}

interface ShapeOverlay {
  /** The whole overlay for this shape, already carrying the shape's transform. */
  readonly node: SvgElement;
  readonly guides: readonly OverlayGuide[];
  readonly handles: readonly OverlayHandle[];
  readonly textRect: ResolvedRect | null;
  readonly connectionSites: readonly ResolvedConnectionSite[];
  /** Paths whose evaluation reached a non-finite number, by index. */
  readonly brokenPaths: readonly number[];
}

function shapeOverlay(placed: Placed, options?: OverlayOptions): ShapeOverlay;

interface MediaImage {
  readonly bytes: Uint8Array;
  readonly contentType: string;
}

type MediaResolver = (embed: string, part: string) => MediaImage | undefined;

function blipPaint(fill: BlipFill, ctx: ColorContext, box: Box, defs: Defs, media: MediaResolver | undefined, size: (bytes: Uint8Array) => ImageSize, uri: (bytes: Uint8Array, contentType: string) => string): Attrs;

type Attrs = Record<string, AttributeValue>;

class Defs {
  private readonly nodes;
  private next;
  /** A per-slide prefix, so two slides in one document cannot collide. */
  private readonly prefix;
  /** How an image fill reaches its picture; absent means none can be drawn. */
  readonly media: MediaResolver | undefined;
  /** Device pixels to the point the slide is drawn at, or null for a scale nobody has named. */
  readonly pxPerPt: number | null;
  constructor(prefix: string, media?: MediaResolver, pxPerPt?: number | null);
  id(): string;
  add(node: SvgElement): void;
  get length(): number;
  toNode(): SvgElement | null;
}

function fillAttributes(fill: Fill | null, ctx: ColorContext, box: Box, defs: Defs): Attrs;

interface StrokePaint {
  readonly attrs: Attrs;
  readonly band: StrokeBand;
  readonly line: ResolvedLine;
  /** Half a device pixel in EMU for an odd pen at a named scale, else zero (F3, `snap.json`). */
  readonly shift: number;
  /** Whether the true width is a whole number of device pixels at the named scale, so the pen is the width. */
  readonly whole: boolean;
}

function strokeAttributes(line: ResolvedLine | null, ctx: ColorContext, box: Box, defs: Defs, forced?: StrokeBand): StrokePaint | null;

function withEffects(children: readonly SvgElement[], effects: readonly Effect[], ctx: ColorContext, box: Box, defs: Defs): readonly SvgElement[];

interface ResolvedRun {
  readonly text: string;
  readonly font: RunFont;
  /** `null` where nothing in the cascade named a colour. */
  readonly color: Rgba | null;
  readonly highlight: Rgba | null;
  readonly underline: Underline | undefined;
  readonly strike: Strike | undefined;
  readonly caps: Caps | undefined;
  /** `a:rPr/@baseline`, thousandths of a percent. */
  readonly baseline: number;
  /** A hard `a:br` ends the line after this run. */
  readonly hardBreak: boolean;
}

interface ResolvedParagraph {
  readonly level: number;
  readonly align: TextAlign;
  /** `@marL` and `@indent`, in points. */
  readonly marginLeft: number;
  readonly indent: number;
  readonly lineSpacing: LineSpacing;
  readonly spaceBefore: LineSpacing;
  readonly spaceAfter: LineSpacing;
  readonly runs: readonly ResolvedRun[];
  /** The properties of the paragraph mark, which set an empty line's height. */
  readonly endRun: ResolvedRun;
  /** What is drawn in front of the first line, or null where the cascade names no bullet. */
  readonly bullet: DrawableBullet<Rgba> | null;
}

interface ResolvedFrame {
  readonly anchor: TextAnchor;
  readonly anchorCtr: boolean;
  readonly vertical: VerticalText;
  readonly wrap: 'none' | 'square';
  /** In points, each edge on its own. */
  readonly insets: {
    left: number;
    top: number;
    right: number;
    bottom: number;
  };
  readonly columns: number;
  readonly columnSpacing: number;
  readonly rtlColumns: boolean;
  /** `a:bodyPr/@rot` in degrees, positive clockwise. */
  readonly bodyRotation: number;
  readonly upright: boolean;
  readonly vertOverflow: 'overflow' | 'ellipsis' | 'clip';
  /** `a:normAutofit/@fontScale` as a multiplier, already quantised. */
  readonly fontScale: number;
  readonly lineSpaceReduction: number;
}

interface ResolvedText {
  readonly frame: ResolvedFrame;
  readonly paragraphs: readonly ResolvedParagraph[];
}

function resolveText(placed: Placed, defaultTextStyle?: ListStyle): ResolvedText | null;

interface TextPiece {
  /** The characters as the file has them, before `@cap`. */
  readonly source: string;
  /** The characters to draw, after `@cap` has been applied. */
  readonly text: string;
  readonly font: RunFont;
  /** The CSS `font-family` value, computed once so two emitters cannot differ. */
  readonly cssFamily: string;
  readonly color: Rgba | null;
  readonly highlight: Rgba | null;
  /** Points from the line's own left edge. */
  readonly leftPt: number;
  readonly widthPt: number;
  /** Points above the line's baseline; a subscript is negative. */
  readonly risePt: number;
  /** The rules this piece draws, already placed. */
  readonly rules: readonly PieceRule[];
  /**
   * The glyphs of this piece, each placed and turned a quarter out of the line.
   *
   * Empty for every piece that flows, which is all of them outside an `eaVert`
   * frame. A piece with entries draws these and not `text`.
   */
  readonly upright: readonly UprightGlyph[];
}

interface UprightGlyph {
  readonly text: string;
  /** The glyph's alphabetic baseline, from the line's own left edge. */
  readonly alongPt: number;
  /** The glyph's own x origin, from the line's own top edge. */
  readonly acrossPt: number;
  /**
   * The `line-height` that lands a browser's baseline `sizePt` below the top.
   *
   * The SVG emitter places a baseline as a coordinate and ignores this; the HTML
   * layer cannot, and a glyph drawn from its own pen is outside the line's own
   * strut. `sizePt` is the anchor because a single glyph has no other.
   */
  readonly strutPt: number;
}

interface PieceRule {
  readonly leftPt: number;
  readonly widthPt: number;
  /** The rule's top edge below the baseline; a strikethrough's is negative. */
  readonly topPt: number;
  readonly thickness: number;
  readonly pattern: DrawnRule['pattern'];
  readonly wavy: boolean;
}

interface TextLine {
  /**
   * The paragraph's bullet, on its first line only, placed from the line's own left edge.
   *
   * Negative `leftPt`, usually: the bullet sits in the hanging indent to the left of the text.
   */
  readonly bullet: TextPiece | null;
  /** Points from the frame's top-left corner, before the block is turned. */
  readonly topPt: number;
  readonly heightPt: number;
  /** The baseline, from the same corner. */
  readonly baselinePt: number;
  readonly leftPt: number;
  readonly widthPt: number;
  /** The largest size on the line, which is what its box follows. */
  readonly sizePt: number;
  /**
   * The CSS `line-height` that lands a browser's baseline on `baselinePt`.
   *
   * A browser puts the baseline of an inline box a half-leading plus an ascent
   * below the line box; solving that for the share PowerPoint uses is one line
   * of arithmetic, done here so the HTML layer and the SVG cannot answer it
   * differently. It lands within one CSS pixel and no closer, because Chromium
   * rounds the font's ascent to a whole pixel before it lays a line out.
   */
  readonly strutPt: number;
  /**
   * Extra advance on every space, in points, from a justifying alignment.
   *
   * A width rather than a set of positions: an emitter that repositioned each
   * word would break the shaping of the line, and T8 measured that a line is
   * shaped whole.
   */
  readonly wordSpacingPt: number;
  readonly pieces: readonly TextPiece[];
}

interface TextBlock {
  /** Degrees clockwise about the frame centre, after every turn is composed. */
  readonly turnDeg: number;
  /** The rectangle the block was laid out in, in the shape's own space. */
  readonly boxPt: Box$1;
  readonly lines: readonly TextLine[];
}

interface LayoutTextOptions {
  /** The shape's own extent, in points. */
  readonly widthPt: number;
  readonly heightPt: number;
  /** `a:xfrm/@rot`, in degrees clockwise, as `Frame` already has it. */
  readonly rot: number;
  readonly flipH: boolean;
  readonly flipV: boolean;
  readonly measurer?: TextMeasurer | undefined;
  readonly faceBox?: FaceBoxProbe | undefined;
  /** The rules for a typeface, so a caller decides what an unmeasured one gets. */
  readonly rulesFor: (typeface: string) => FaceRules;
  /** The CSS `font-family` a piece is drawn in; defaults to the run's own family, quoted. */
  readonly cssFamilyFor?: ((font: RunFont) => string) | undefined;
}

const SHIFT_SIZE_RATIO: number;

const SMALL_CAPS_RATIO = 0.8;

function textTurn(frame: ResolvedFrame, options: Pick<LayoutTextOptions, 'widthPt' | 'heightPt' | 'rot' | 'flipH' | 'flipV'>): {
  turnDeg: number;
  boxPt: Box$1;
};

function capStretches(text: string, caps: string | undefined): readonly CapStretch[];

function alignOffset(align: string, columnWidthPt: number, anchorWidthPt: number): number;

function stretches(align: string, lastLine: boolean): boolean;

function layoutText(text: ResolvedText, options: LayoutTextOptions): TextBlock;

function strutHeight(dropPt: number, face: FaceBox, sizePt: number): number;

interface TextOptions {
  /** `p:defaultTextStyle`, the cascade's seventh source. */
  readonly defaultTextStyle?: ListStyle | undefined;
  /** Defaults to one over `OffscreenCanvas`, which needs a browser or a Worker. */
  readonly measurer?: TextMeasurer | undefined;
  readonly faceBox?: FaceBoxProbe | undefined;
  /**
   * What to do about a typeface whose rules nobody measured.
   *
   * Defaults to Arial's, because a renderer that refused to draw an underline on
   * an unmeasured face would refuse most decks. A caller that wants the
   * diagnostic passes `faceRules` itself and handles the throw.
   */
  readonly rulesFor?: ((typeface: string) => FaceRules) | undefined;
  /**
   * The CSS `font-family` a run is drawn in.
   *
   * Defaults to the run's own family, quoted, which is right where the caller
   * measures through that same name; a caller that measured in another face
   * names it here so the markup says what was drawn.
   */
  readonly cssFamilyFor?: ((font: RunFont) => string) | undefined;
}

function approximateRules(typeface: string): FaceRules;

interface TextEngine {
  readonly defaultTextStyle: ListStyle | undefined;
  readonly measurer: TextMeasurer;
  readonly faceBox: FaceBoxProbe;
  readonly rulesFor: (typeface: string) => FaceRules;
  readonly cssFamilyFor: (font: RunFont) => string;
}

function createTextEngine(options?: TextOptions): TextEngine;

function textBlockOf(placed: Placed, engine: TextEngine): TextBlock | null;

function shapeTextNodes(placed: Placed, engine: TextEngine): readonly SvgNode[];

function shapeNodes(placed: Placed, defs: Defs, text?: TextEngine | null): readonly SvgNode[];

function textNodes(block: TextBlock, frame: {
  x: number;
  y: number;
  cx: number;
  cy: number;
}, attrs?: Record<string, string | number | null>): readonly SvgNode[];

interface SlideSize {
  readonly cx: number;
  readonly cy: number;
}

interface RenderOptions {
  /**
   * A prefix for every generated `id`.
   *
   * Two slides in one HTML document share a URL space, so a `url(#g-1)` from
   * the second silently paints with the first's gradient unless the ids differ.
   * Defaults to something unique per call.
   */
  readonly idPrefix?: string;
  /** The `width` attribute in CSS pixels, which also names the device scale strokes round to. */
  readonly width?: number;
  /** The `height` attribute in CSS pixels: a box the slide is stretched into, as the export is (F2). */
  readonly height?: number;
  /** Device pixels per CSS pixel, so a 2x display rounds strokes to its own pixels. Default 1. */
  readonly devicePixelRatio?: number;
  /** Leave off `xmlns`, for a fragment going into an existing SVG document. */
  readonly inline?: boolean;
  /** Draw the master's and layout's shapes beneath the sheet's own. Default true. */
  readonly inherited?: boolean;
  /**
   * How an image fill or picture reaches its bytes.
   *
   * The renderer resolves no relationships: a fill written in a layout means
   * the layout part own rels, and only the caller knows which part it came from.
   */
  readonly media?: MediaResolver;
  /**
   * How to draw text, or `false` to draw none.
   *
   * Text needs a measuring surface, so a caller with no `OffscreenCanvas` - a
   * Node script, a test asserting geometry alone - turns it off rather than
   * getting a throw from a package it did not know it was using.
   */
  readonly text?: TextOptions | false;
}

interface SlideRender {
  readonly node: SvgElement;
  readonly placed: readonly Placed[];
}

function slideNode(sheet: Sheet, size: SlideSize, options?: RenderOptions): SlideRender;

function renderSlide(sheet: Sheet, size: SlideSize, options?: RenderOptions): string;

function imageSize(bytes: Uint8Array): ImageSize;

function dataUri(bytes: Uint8Array, contentType: string): string;

interface MediaStore {
  relationships(part: string): {
    targetOf(id: string): string | undefined;
  };
  contentTypeOf(part: string): string | undefined;
  read(part: string): Uint8Array;
}

function mediaFromStore(store: MediaStore): MediaResolver;