docgen-utils 1.0.5

package/dist/packages/slides/vendor/pptxgen.d.ts

@@ -0,0 +1,805 @@
+/**
+ * Type declarations for the vendored PptxGenJS 4.0.1 (patched).
+ *
+ * This file covers the full PptxGenJS API surface used by the slide pipeline,
+ * including our custom patches:
+ *   - Gradient fills (GradientStop, GradientFillProps, ShapeFillProps.type 'gradient')
+ *   - fontFill on text run properties (gradient text fills)
+ *   - rectRadius on ImageOptions (rounded image corners)
+ *   - Default text valign changed to 'top'
+ *   - 'c' prefix accepted for center valign
+ *
+ * Upstream source: PptxGenJS 4.0.1
+ * Patch: pptxgen_patch.patch
+ */
+
+// ---------------------------------------------------------------------------
+// Core scalar types
+// ---------------------------------------------------------------------------
+
+/** Hex color string (6-character, no leading '#'). */
+export type HexColor = string;
+
+/** Theme/scheme color token. */
+export type ThemeColor =
+  | 'tx1' | 'tx2'
+  | 'bg1' | 'bg2'
+  | 'accent1' | 'accent2' | 'accent3' | 'accent4' | 'accent5' | 'accent6';
+
+/** A color is either a hex string or a theme color token. */
+export type Color = HexColor | ThemeColor;
+
+/**
+ * Coordinate value - inches (number) or percentage string.
+ * @example 10.25 // inches
+ * @example '75%' // percentage of slide size
+ */
+export type Coord = number | `${number}%`;
+
+/** Margin as uniform points or [left, right, bottom, top]. */
+export type Margin = number | [number, number, number, number];
+
+export type HAlign = 'left' | 'center' | 'right' | 'justify';
+export type VAlign = 'top' | 'middle' | 'bottom';
+
+export type OutputType =
+  | 'arraybuffer'
+  | 'base64'
+  | 'binarystring'
+  | 'blob'
+  | 'nodebuffer'
+  | 'uint8array';
+
+// ---------------------------------------------------------------------------
+// Position
+// ---------------------------------------------------------------------------
+
+export interface PositionProps {
+  /** Horizontal position (inches or percentage). */
+  x?: Coord;
+  /** Vertical position (inches or percentage). */
+  y?: Coord;
+  /** Width (inches or percentage). */
+  w?: Coord;
+  /** Height (inches or percentage). */
+  h?: Coord;
+}
+
+// ---------------------------------------------------------------------------
+// Gradient fills  (CUSTOM PATCH)
+// ---------------------------------------------------------------------------
+
+/** Single color stop within a gradient. */
+export interface GradientStop {
+  /** Color at this stop (hex or theme color). */
+  color: Color;
+  /** Position of the stop (0-100). */
+  position: number;
+  /**
+   * Transparency at this stop (0-100).
+   * @default 0
+   */
+  transparency?: number;
+}
+
+/** Gradient fill configuration. */
+export interface GradientFillProps {
+  /** Gradient type. */
+  type: 'linear' | 'radial';
+  /**
+   * Angle in CSS degrees for linear gradients (0-359).
+   * - 0 = bottom-to-top, 90 = left-to-right, 180 = top-to-bottom
+   * @default 0
+   */
+  angle?: number;
+  /** Array of color stops (must have >= 2 entries). */
+  stops: GradientStop[];
+  /**
+   * Center X for radial gradients (0-100).
+   * @default 50
+   */
+  centerX?: number;
+  /**
+   * Center Y for radial gradients (0-100).
+   * @default 50
+   */
+  centerY?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Fill / Line / Shadow
+// ---------------------------------------------------------------------------
+
+/**
+ * Shape fill properties.
+ *
+ * Simple solid fill:
+ * ```ts
+ * { color: 'FF0000' }
+ * { color: 'FF0000', transparency: 50 }
+ * ```
+ *
+ * Gradient fill (CUSTOM PATCH):
+ * ```ts
+ * { type: 'gradient', gradient: { type: 'linear', angle: 90, stops: [...] } }
+ * ```
+ */
+export interface ShapeFillProps {
+  /** Fill color (hex or theme). Required for solid fills. */
+  color?: Color;
+  /**
+   * Fill type.
+   * @default 'solid'
+   */
+  type?: 'none' | 'solid' | 'gradient';
+  /**
+   * Gradient fill properties.
+   * Required when `type` is `'gradient'`.
+   */
+  gradient?: GradientFillProps;
+  /**
+   * Transparency (percent, 0-100).
+   * @default 0
+   */
+  transparency?: number;
+  /**
+   * @deprecated v3.3.0 - use `transparency`
+   */
+  alpha?: number;
+}
+
+/** Shape/line outline properties. */
+export interface ShapeLineProps extends ShapeFillProps {
+  /**
+   * Line width (points).
+   * @default 1
+   */
+  width?: number;
+  /** Dash type. */
+  dashType?:
+    | 'solid'
+    | 'dash'
+    | 'dashDot'
+    | 'lgDash'
+    | 'lgDashDot'
+    | 'lgDashDotDot'
+    | 'sysDash'
+    | 'sysDot';
+  /** Begin arrow type. */
+  beginArrowType?: 'none' | 'arrow' | 'diamond' | 'oval' | 'stealth' | 'triangle';
+  /** End arrow type. */
+  endArrowType?: 'none' | 'arrow' | 'diamond' | 'oval' | 'stealth' | 'triangle';
+  /**
+   * Line width (points).
+   * @deprecated v3.3.0 - use `width`
+   */
+  pt?: number;
+  /**
+   * Line size (points).
+   * @deprecated v3.3.0 - use `width`
+   */
+  size?: number;
+}
+
+/** Shadow properties for shapes, text, and images. */
+export interface ShadowProps {
+  /**
+   * Shadow type.
+   * @default 'none'
+   */
+  type: 'outer' | 'inner' | 'none';
+  /**
+   * Opacity (0.0 - 1.0).
+   * @example 0.5
+   */
+  opacity?: number;
+  /**
+   * Blur radius (points, 0-100).
+   * @default 0
+   */
+  blur?: number;
+  /**
+   * Angle (degrees, 0-359).
+   * @default 0
+   */
+  angle?: number;
+  /**
+   * Shadow offset (points, 0-200).
+   * @default 0
+   */
+  offset?: number;
+  /**
+   * Shadow color (hex).
+   * @example 'FF3399'
+   */
+  color?: HexColor;
+  /**
+   * Whether to rotate the shadow with the shape.
+   * @default false
+   */
+  rotateWithShape?: boolean;
+}
+
+/** Border properties used by charts, shapes, and tables. */
+export interface BorderProps {
+  /** Border type. */
+  type?: 'none' | 'dash' | 'solid';
+  /** Border color (hex). */
+  color?: HexColor;
+  /** Border size (points). */
+  pt?: number;
+}
+
+/** Hyperlink properties. */
+export interface HyperlinkProps {
+  /** Target slide number. */
+  slide?: number;
+  /** Target URL. */
+  url?: string;
+  /** Tooltip text. */
+  tooltip?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Text properties
+// ---------------------------------------------------------------------------
+
+/** Underline style options. */
+export interface UnderlineProps {
+  style?:
+    | 'dash'
+    | 'dashHeavy'
+    | 'dashLong'
+    | 'dashLongHeavy'
+    | 'dbl'
+    | 'dotDash'
+    | 'dotDashHeave'
+    | 'dotDotDash'
+    | 'dotDotDashHeavy'
+    | 'dotted'
+    | 'dottedHeavy'
+    | 'heavy'
+    | 'none'
+    | 'sng'
+    | 'wavy'
+    | 'wavyDbl'
+    | 'wavyHeavy';
+  color?: Color;
+}
+
+/** Text glow effect. */
+export interface TextGlowProps {
+  /** Glow size (points). */
+  size?: number;
+  /** Glow color. */
+  color?: Color;
+  /** Glow opacity. */
+  opacity?: number;
+}
+
+/** Bullet configuration. */
+export interface BulletProps {
+  /** Bullet type. */
+  type?: 'bullet' | 'number';
+  /** Bullet character code (unicode). */
+  characterCode?: string;
+  /** Indent between bullet and text (points). */
+  indent?: number;
+  /** Number type (for numbered lists). */
+  numberType?:
+    | 'alphaLcParenBoth'
+    | 'alphaLcParenR'
+    | 'alphaLcPeriod'
+    | 'alphaUcParenBoth'
+    | 'alphaUcParenR'
+    | 'alphaUcPeriod'
+    | 'arabicParenBoth'
+    | 'arabicParenR'
+    | 'arabicPeriod'
+    | 'arabicPlain'
+    | 'romanLcParenBoth'
+    | 'romanLcParenR'
+    | 'romanLcPeriod'
+    | 'romanUcParenBoth'
+    | 'romanUcParenR'
+    | 'romanUcPeriod';
+  /** Start number for numbered bullets. */
+  numberStartAt?: number;
+  /**
+   * @deprecated v3.3.0 - use `characterCode`
+   */
+  code?: string;
+  /**
+   * @deprecated v3.3.0 - use `indent`
+   */
+  marginPt?: number;
+  /**
+   * @deprecated v3.3.0 - use `numberStartAt`
+   */
+  startAt?: number;
+}
+
+/**
+ * Base text properties shared by text runs, table cells, and shape text.
+ *
+ * Note: default valign changed from 'center' to 'top' in our patch for
+ * consistency with CSS rendering.
+ */
+export interface TextBaseProps {
+  /** Horizontal alignment. */
+  align?: HAlign;
+  /** Bold. */
+  bold?: boolean;
+  /** Insert a line break before this run. */
+  breakLine?: boolean;
+  /** Bullet options (true for default bullet, or BulletProps). */
+  bullet?: boolean | BulletProps;
+  /**
+   * Text color (hex or theme).
+   * Ignored when `fontFill` is set.
+   */
+  color?: Color;
+  /**
+   * Text fill (supports gradient fills).  CUSTOM PATCH.
+   * Takes priority over `color` when set.
+   * @example { type: 'gradient', gradient: { type: 'linear', angle: 90, stops: [...] } }
+   */
+  fontFill?: ShapeFillProps;
+  /** Font face name. */
+  fontFace?: string;
+  /** Font size (points). */
+  fontSize?: number;
+  /** Text highlight color (hex). */
+  highlight?: HexColor;
+  /** Indent level (0-based). */
+  indentLevel?: number;
+  /** Italic. */
+  italic?: boolean;
+  /** Language (ISO 639-1). */
+  lang?: string;
+  /** Soft line break (shift+enter) before content. */
+  softBreakBefore?: boolean;
+  /** Tab stop positions. */
+  tabStops?: Array<{ position: number; alignment?: 'l' | 'r' | 'ctr' | 'dec' }>;
+  /** Transparency (percent, 0-100). */
+  transparency?: number;
+  /** Underline options. */
+  underline?: boolean | UnderlineProps;
+  /**
+   * Vertical alignment.
+   * Accepts 'top', 'middle', 'bottom'. Our patch also accepts leading 'c' for center.
+   * @default 'top'
+   */
+  valign?: VAlign;
+  /** Character spacing (points). */
+  charSpacing?: number;
+  /** Text glow effect. */
+  glow?: TextGlowProps;
+  /** Text outline. */
+  outline?: { size?: number; color?: Color };
+  /** Text direction. */
+  textDirection?: 'horz' | 'vert' | 'vert270' | 'wordArtVert';
+}
+
+// ---------------------------------------------------------------------------
+// Text options (for addText)
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for `Slide.addText()`.
+ * Combines position, text-base props, and shape-level props.
+ */
+export interface TextOptions extends PositionProps, TextBaseProps {
+  /** Shape fill. */
+  fill?: ShapeFillProps;
+  /** Shape line/border. */
+  line?: ShapeLineProps;
+  /** Shape shadow. */
+  shadow?: ShadowProps;
+  /** Margin (points). */
+  margin?: Margin;
+  /** Paragraph spacing before (points). */
+  paraSpaceBefore?: number;
+  /** Paragraph spacing after (points). */
+  paraSpaceAfter?: number;
+  /** Line spacing (points). */
+  lineSpacing?: number;
+  /** Line spacing multiplier. */
+  lineSpacingMultiple?: number;
+  /** Hyperlink. */
+  hyperlink?: HyperlinkProps;
+  /** Shape type for the text box background. */
+  shape?: string;
+  /** Rounded rectangle radius (inches). */
+  rectRadius?: number;
+  /** Rotation (degrees, -360 to 360). */
+  rotate?: number;
+  /** Text wrapping. */
+  wrap?: boolean;
+  /** Internal inset (points). */
+  inset?: number;
+  /** Auto-fit text to shape. */
+  autoFit?: boolean;
+  /** Auto-shrink text to fit. */
+  shrinkText?: boolean;
+  /** Object name. */
+  objectName?: string;
+  /** Placeholder type name. */
+  placeholder?: string;
+  /** Vertical text direction. */
+  vert?: string;
+}
+
+/** Single text run within a rich-text array. */
+export interface TextRun {
+  text: string;
+  options?: TextBaseProps;
+}
+
+/** Text argument for addText: plain string or array of text runs. */
+export type TextProps = string | TextRun[];
+
+// ---------------------------------------------------------------------------
+// Image options
+// ---------------------------------------------------------------------------
+
+/** Image sizing configuration. */
+export interface ImageSizing {
+  type: 'contain' | 'cover' | 'crop';
+  w: Coord;
+  h: Coord;
+  x?: Coord;
+  y?: Coord;
+}
+
+/** Options for `Slide.addImage()`. */
+export interface ImageOptions extends PositionProps {
+  /** Base64-encoded image data. */
+  data?: string;
+  /** URL or file path. */
+  path?: string;
+  /** Image sizing / cropping. */
+  sizing?: ImageSizing;
+  /** Render as ellipse. */
+  rounding?: boolean;
+  /**
+   * Rounded rectangle clip radius (inches). CUSTOM PATCH.
+   * Overrides `rounding` when set.
+   * @example 0.2
+   */
+  rectRadius?: number;
+  /** Shadow. */
+  shadow?: ShadowProps;
+  /** Hyperlink. */
+  hyperlink?: HyperlinkProps;
+  /** Rotation (degrees). */
+  rotate?: number;
+  /** Alt text. */
+  altText?: string;
+  /** Transparency (percent, 0-100). */
+  transparency?: number;
+  /** Flip horizontally. */
+  flipH?: boolean;
+  /** Flip vertically. */
+  flipV?: boolean;
+  /** Object name. */
+  objectName?: string;
+  /** Placeholder type. */
+  placeholder?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Shape options
+// ---------------------------------------------------------------------------
+
+/** Options for `Slide.addShape()`. */
+export interface ShapeOptions extends PositionProps {
+  /** Shape fill (solid or gradient). */
+  fill?: ShapeFillProps;
+  /** Shape line/border. */
+  line?: ShapeLineProps;
+  /** Shadow. */
+  shadow?: ShadowProps;
+  /** Rounded rectangle radius (0.0-1.0 or inches depending on context). */
+  rectRadius?: number;
+  /** Rotation (degrees). */
+  rotate?: number;
+  /** Flip horizontally. */
+  flipH?: boolean;
+  /** Flip vertically. */
+  flipV?: boolean;
+  /** Hyperlink. */
+  hyperlink?: HyperlinkProps;
+  /** Object name. */
+  objectName?: string;
+  /** Horizontal alignment. */
+  align?: HAlign;
+  /**
+   * Arc angle range (for PIE, ARC, BLOCK_ARC shapes).
+   * @example [270, 0]
+   */
+  angleRange?: [number, number];
+  /** Block-arc thickness ratio (0.0-1.0). */
+  arcThicknessRatio?: number;
+  /** Custom geometry points. */
+  points?: Array<Record<string, unknown>>;
+}
+
+// ---------------------------------------------------------------------------
+// Table types
+// ---------------------------------------------------------------------------
+
+export interface TableCellProps extends TextBaseProps {
+  border?: BorderProps | [BorderProps, BorderProps, BorderProps, BorderProps];
+  colspan?: number;
+  fill?: ShapeFillProps;
+  hyperlink?: HyperlinkProps;
+  margin?: Margin;
+  rowspan?: number;
+}
+
+export interface TableCell {
+  text: string | TextRun[];
+  options?: TableCellProps;
+}
+
+export type TableRow = TableCell[];
+
+export interface TableProps extends PositionProps, TextBaseProps {
+  autoPage?: boolean;
+  autoPageCharWeight?: number;
+  autoPageLineWeight?: number;
+  autoPageRepeatHeader?: boolean;
+  autoPageSlideStartY?: number;
+  colW?: number | number[];
+  rowH?: number | number[];
+  border?: BorderProps | [BorderProps, BorderProps, BorderProps, BorderProps];
+  fill?: ShapeFillProps;
+  margin?: Margin;
+  objectName?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Background
+// ---------------------------------------------------------------------------
+
+export interface BackgroundProps extends ShapeFillProps {
+  /** Base64-encoded image data. */
+  data?: string;
+  /** Image path/URL. */
+  path?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Write options
+// ---------------------------------------------------------------------------
+
+export interface WriteBaseProps {
+  /** Compression (can reduce file size ~30%). */
+  compression?: boolean;
+}
+
+export interface WriteOptions extends WriteBaseProps {
+  /** Output type. */
+  outputType?: OutputType;
+}
+
+export interface WriteFileProps extends WriteBaseProps {
+  /** Output file name. */
+  fileName?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Layout
+// ---------------------------------------------------------------------------
+
+export interface PresLayout {
+  /** Layout name. */
+  name: string;
+  /** Width in EMU (914400 EMU per inch). */
+  width: number;
+  /** Height in EMU (914400 EMU per inch). */
+  height: number;
+}
+
+// ---------------------------------------------------------------------------
+// Slide
+// ---------------------------------------------------------------------------
+
+export interface Slide {
+  /**
+   * Add text to the slide.
+   * @param text - Plain string or array of TextRun objects for rich text.
+   * @param options - Position, formatting, and shape options.
+   */
+  addText(
+    text: string | TextRun[],
+    options?: TextOptions,
+  ): Slide;
+
+  /**
+   * Add an image to the slide.
+   * @param options - Image source, position, sizing, and rounding options.
+   */
+  addImage(options: ImageOptions): Slide;
+
+  /**
+   * Add a shape to the slide.
+   * @param shapeName - Shape type name (e.g. 'rect', 'roundRect', 'line').
+   * @param options - Position, fill, line, shadow, and other shape options.
+   */
+  addShape(shapeName: string, options?: ShapeOptions): Slide;
+
+  /**
+   * Add a table to the slide.
+   * @param rows - Array of row arrays, each containing TableCell objects.
+   * @param options - Table layout and style options.
+   */
+  addTable(rows: TableRow[], options?: TableProps): Slide;
+
+  /**
+   * Add a chart to the slide.
+   * @param type - Chart type string.
+   * @param data - Chart data series.
+   * @param options - Chart options.
+   */
+  addChart(
+    type: string,
+    data: Record<string, unknown>[],
+    options?: Record<string, unknown>,
+  ): Slide;
+
+  /**
+   * Add media (audio/video) to the slide.
+   * @param options - Media options including type, path/data, and position.
+   */
+  addMedia(options: Record<string, unknown>): Slide;
+
+  /**
+   * Add speaker notes to the slide.
+   * @param notes - Plain text notes content.
+   */
+  addNotes(notes: string): Slide;
+
+  /**
+   * Slide background.
+   * Set to `{ color: 'FFFFFF' }` for solid, or use gradient/image props.
+   */
+  background: BackgroundProps;
+
+  /** Slide number (1-based, read-only at runtime). */
+  readonly _slideNum: number;
+}
+
+// ---------------------------------------------------------------------------
+// PptxGenJS class
+// ---------------------------------------------------------------------------
+
+/**
+ * PptxGenJS presentation generator.
+ *
+ * This is the vendored & patched build (4.0.1). See `slides/vendor/VENDORING.md`.
+ */
+declare class PptxGenJS {
+  /**
+   * Library version string.
+   */
+  readonly version: string;
+
+  /**
+   * Resolved presentation layout dimensions.
+   * Width and height are in EMU (914400 EMU = 1 inch).
+   */
+  readonly presLayout: PresLayout;
+
+  /**
+   * All slides in the presentation (read-only array).
+   */
+  readonly slides: Slide[];
+
+  /**
+   * Shape type constants.
+   * @example pptx.ShapeType.rect, pptx.ShapeType.roundRect, pptx.ShapeType.line
+   */
+  readonly ShapeType: Record<string, string>;
+
+  /**
+   * Horizontal alignment enum.
+   */
+  readonly AlignH: Record<string, string>;
+
+  /**
+   * Vertical alignment enum.
+   */
+  readonly AlignV: Record<string, string>;
+
+  /**
+   * Chart type enum.
+   */
+  readonly ChartType: Record<string, string>;
+
+  /**
+   * Scheme color enum.
+   */
+  readonly SchemeColor: Record<string, string>;
+
+  // ---- Presentation metadata ----
+
+  /**
+   * Presentation layout name.
+   * Standard: 'LAYOUT_4x3', 'LAYOUT_16x9', 'LAYOUT_16x10', 'LAYOUT_WIDE'.
+   */
+  layout: string;
+
+  /** Whether Right-to-Left mode is enabled. */
+  rtlMode: boolean;
+
+  /** Author metadata. */
+  author: string;
+  /** Company metadata. */
+  company: string;
+  /** Revision number (must be a whole number). */
+  revision: string;
+  /** Subject metadata. */
+  subject: string;
+  /** Title metadata. */
+  title: string;
+  /** Theme (default fonts). */
+  theme: { headFontFace?: string; bodyFontFace?: string };
+
+  // ---- Methods ----
+
+  /**
+   * Add a new slide to the presentation.
+   * @param masterName - Optional master slide name or options.
+   */
+  addSlide(masterName?: string | { masterName?: string; sectionTitle?: string }): Slide;
+
+  /**
+   * Define a custom slide layout.
+   * @param layout - Layout dimensions.
+   */
+  defineLayout(layout: PresLayout): void;
+
+  /**
+   * Define a slide master (layout template).
+   * @param props - Master slide properties.
+   */
+  defineSlideMaster(props: Record<string, unknown>): void;
+
+  /**
+   * Export the presentation to a buffer/string.
+   * @param options - Output type and compression.
+   */
+  write(options?: WriteOptions): Promise<string | ArrayBuffer | Blob | Uint8Array | Buffer>;
+
+  /**
+   * Export the presentation to a file (Node.js) or trigger download (browser).
+   * @param options - Output file name and compression.
+   */
+  writeFile(options?: WriteFileProps): Promise<string>;
+
+  /**
+   * Export the presentation as a stream.
+   * @param options - Compression options.
+   */
+  stream(options?: WriteBaseProps): Promise<string | ArrayBuffer | Blob | Uint8Array>;
+
+  /**
+   * Add a section to the presentation.
+   * @param props - Section properties.
+   */
+  addSection(props: { title: string }): void;
+
+  /**
+   * Convert an HTML table element to slides.
+   * @param eleId - HTML element ID.
+   * @param props - Options for table-to-slides conversion.
+   */
+  tableToSlides(eleId: string, props?: Record<string, unknown>): void;
+}
+
+export default PptxGenJS;
+export {
+  PptxGenJS,
+};