@silurus/ooxml 0.57.0 → 0.58.0

package/dist/types/pptx.d.ts

@@ -514,7 +514,20 @@ declare interface EquationRun {
     color?: string | null;
 }
 
-export declare type Fill = SolidFill | NoFill | GradientFill | PatternFill;
+export declare type Fill = SolidFill | NoFill | GradientFill | PatternFill | ImageFill;
+
+/**
+ * ECMA-376 §20.1.8.30 (CT_RelativeRect) — the destination rectangle a stretched
+ * blip is mapped into, as edge insets relative to the fill region. Values are
+ * fractions (ST_Percentage / 100000); **negative values let the image bleed
+ * past the box (overscan)**. Absent edges default to 0.
+ */
+export declare interface FillRect {
+    l?: number;
+    t?: number;
+    r?: number;
+    b?: number;
+}
 
 /** ECMA-376 §20.1.8.17 (CT_GlowEffect) — coloured halo with blur radius. */
 export declare interface Glow {
@@ -538,6 +551,30 @@ export declare interface GradientStop {
     color: string;
 }
 
+/**
+ * Image fill — ECMA-376 §20.1.8.14 (CT_BlipFillProperties). The embedded blip
+ * is resolved to a base64 data URL at parse time. Both fill-modes are modelled
+ * and mutually exclusive: `stretch` (§20.1.8.56) carries {@link ImageFill.fillRect};
+ * `tile` (§20.1.8.58) carries {@link ImageFill.tile}.
+ */
+export declare interface ImageFill {
+    fillType: 'image';
+    /** `data:<mime>;base64,…` of the embedded blip. */
+    dataUrl: string;
+    /**
+     * `<a:stretch><a:fillRect>` insets. Absent → fills the whole box (or the
+     * fill is tiled — see {@link ImageFill.tile}).
+     */
+    fillRect?: FillRect;
+    /**
+     * `<a:tile>` descriptor. Present only when the blipFill is tiled; mutually
+     * exclusive with {@link ImageFill.fillRect}.
+     */
+    tile?: TileInfo;
+    /** `a:blip > a:alphaModFix@amt` as a fraction (0.0–1.0). Absent = opaque. */
+    alpha?: number;
+}
+
 declare interface LegendManualLayout {
     /** `"edge"` = `x`/`y` are fractions from top-left of chart space;
      *  `"factor"` = fractions offset from the default position. */
@@ -551,8 +588,8 @@ declare interface LegendManualLayout {
 }
 
 /**
- * `<a:lightRig>` — ECMA-376 §20.1.5.9 (`CT_LightRig`). Parsed for Phase B
- * (lighting/bevel shading); the Phase A camera renderer ignores it.
+ * `<a:lightRig>` — ECMA-376 §20.1.5.9 (`CT_LightRig`). Drives the bevel-lip
+ * lighting (Phase B): `dir` selects the key-light octant.
  */
 export declare interface LightRig {
     /** Light-rig preset (`ST_LightRigType`), e.g. "threePt". */
@@ -914,6 +951,17 @@ export declare interface PictureElement {
     sp3d?: Sp3d;
 }
 
+/** A single legacy slide comment (`<p:cm>` in `ppt/comments/commentN.xml`). */
+export declare interface PptxComment {
+    /** Resolved author name from `ppt/commentAuthors.xml`. Absent when the
+     *  authors file is missing or the `authorId` is out of range. */
+    author?: string;
+    /** `<p:cm @dt>` — ISO-8601 timestamp the comment was authored. */
+    date?: string;
+    /** Plain-text comment body (`<p:text>`). */
+    text: string;
+}
+
 /**
  * Headless PPTX rendering engine.
  *
@@ -951,6 +999,26 @@ export declare class PptxPresentation {
     get slideWidth(): number;
     /** Slide height in EMU. */
     get slideHeight(): number;
+    /**
+     * Speaker-notes text for a slide (`ppt/notesSlides/notesSlideN.xml`,
+     * ECMA-376 §13.3.5 — Notes Slide). Returns the notes-body text as a single
+     * string (paragraphs joined with `\n`), or `null` when the slide has no
+     * notes part. The notes are parsed at {@link load} time, so this is a
+     * synchronous lookup.
+     *
+     * `slideIndex` is 0-based. Unlike navigation methods it is *not* clamped:
+     * an out-of-range or non-integer index returns `null` rather than the notes
+     * of the nearest slide (so a tool iterating by index gets an honest "no
+     * notes" instead of a duplicated neighbour).
+     *
+     * @example
+     * const pres = await PptxPresentation.load(buffer);
+     * for (let i = 0; i < pres.slideCount; i++) {
+     *   const notes = pres.getNotes(i);
+     *   if (notes) console.log(`Slide ${i + 1} notes:`, notes);
+     * }
+     */
+    getNotes(slideIndex: number): string | null;
     /** Render a slide onto the given canvas. */
     renderSlide(canvas: HTMLCanvasElement, slideIndex: number, opts?: RenderSlideOptions): Promise<void>;
     /**
@@ -1035,6 +1103,13 @@ export declare class PptxViewer {
     prevSlide(): Promise<void>;
     get slideIndex(): number;
     get slideCount(): number;
+    /**
+     * Speaker-notes text for a slide (`ppt/notesSlides/notesSlideN.xml`,
+     * ECMA-376 §13.3.5). Passthrough to {@link PptxPresentation.getNotes}:
+     * 0-based index, returns `null` when the slide has no notes part, the index
+     * is out of range, or nothing is loaded yet.
+     */
+    getNotes(slideIndex: number): string | null;
     /** The underlying <canvas> element. */
     get canvasElement(): HTMLCanvasElement;
     private renderCurrentSlide;
@@ -1255,6 +1330,20 @@ export declare interface Slide {
     slideNumber: number;
     background: Fill | null;
     elements: SlideElement[];
+    /**
+     * Speaker-notes pane text from `ppt/notesSlides/notesSlideN.xml`
+     * (ECMA-376 §13.3.5 — Notes Slide). The full notes-body text as a single
+     * string, paragraphs joined with `\n`. Absent (`undefined`) when the slide
+     * has no notes part. The renderer ignores this — it is surfaced for tools;
+     * read it via {@link PptxPresentation.getNotes}.
+     */
+    notes?: string;
+    /**
+     * Legacy slide comments (`ppt/comments/commentN.xml`, ECMA-376 §13.3.4).
+     * Modern Office 365 threaded comments are not parsed. Omitted from the JSON
+     * when the slide has no comments.
+     */
+    comments?: PptxComment[];
 }
 
 export declare type SlideElement = ShapeElement | PictureElement | TableElement | ChartElement | MediaElement;
@@ -1280,9 +1369,10 @@ export declare interface SolidFill {
 }
 
 /**
- * `<a:sp3d>` — ECMA-376 §20.1.5.12 (`CT_Shape3D`). Parsed in full but **not
- * rendered in Phase A** (camera-only). bevel/contour/extrusion are Phase B.
- * Numeric fields are omitted from JSON when zero.
+ * `<a:sp3d>` — ECMA-376 §20.1.5.12 (`CT_Shape3D`). Rendered in Phase B: bevelT/
+ * bevelB are shaded as a lit lip (distance-field + lightRig), extrusionH as a
+ * swept side wall, and contour as a flat outline approximation. Numeric fields
+ * are omitted from JSON when zero.
  */
 export declare interface Sp3d {
     /** Z position of the front face in EMU (default 0). */
@@ -1528,4 +1618,27 @@ export declare interface TextRunData {
     outline?: TextOutline;
 }
 
+/**
+ * ECMA-376 §20.1.8.58 (CT_TileInfoProperties) — tiled blip-fill placement.
+ * The blip repeats at its native size (scaled by sx/sy) across the fill box.
+ * Mutually exclusive with {@link ImageFill.fillRect} (the `stretch` mode).
+ */
+export declare interface TileInfo {
+    /** Horizontal offset of the first tile, in EMU (`tx`). Default 0. */
+    tx: number;
+    /** Vertical offset of the first tile, in EMU (`ty`). Default 0. */
+    ty: number;
+    /** Horizontal tile scale as a fraction (`sx` / 100000). Default 1.0. */
+    sx: number;
+    /** Vertical tile scale as a fraction (`sy` / 100000). Default 1.0. */
+    sy: number;
+    /** Mirror mode: `'none' | 'x' | 'y' | 'xy'` (`flip`). Default `'none'`. */
+    flip: string;
+    /**
+     * Anchor corner the tile grid registers against:
+     * `tl|t|tr|l|ctr|r|bl|b|br` (`algn`). Default `'tl'`.
+     */
+    algn: string;
+}
+
 export { }

package/dist/types/xlsx.d.ts

@@ -169,6 +169,8 @@ export declare type CfRule = {
 } | {
     type: 'aboveAverage';
     aboveAverage: boolean;
+    equalAverage?: boolean;
+    stdDev?: number;
     dxfId: number | null;
     priority: number;
 } | {
@@ -345,6 +347,28 @@ export declare interface DataPointOverride {
     markerLine?: string;
 }
 
+/** One `<dataValidation>` rule (ECMA-376 §18.3.1.33). `type` is the constraint
+ *  class (`list` | `whole` | `decimal` | `date` | `time` | `textLength` |
+ *  `custom`); `operator` qualifies it (`between` | `notBetween` | `equal` | …).
+ *  `formula1` / `formula2` are the operands (for `list`, `formula1` is the
+ *  comma-separated literal list or a range/named reference). 1:1 with the Rust
+ *  `DataValidation` (serde camelCase). */
+export declare interface DataValidation {
+    /** Affected cell ranges, verbatim from `@sqref` (space-separated A1 refs). */
+    sqref: string;
+    /** Constraint class. Absent means the spec default (`none`, no constraint). */
+    validationType?: string;
+    operator?: string;
+    formula1?: string;
+    formula2?: string;
+    /** `@allowBlank` — empty input is permitted. */
+    allowBlank?: boolean;
+    promptTitle?: string;
+    prompt?: string;
+    errorTitle?: string;
+    errorMessage?: string;
+}
+
 export declare interface DefinedName {
     name: string;
     formula: string;
@@ -710,6 +734,20 @@ export declare interface RenderViewportOptions {
     } | null;
 }
 
+/**
+ * Resolved allowed-value set for a list validation. Either concrete display
+ * `values` (inline list or expanded range), or — when the operand is a defined
+ * name / complex formula we cannot expand — the raw `formula` text so the panel
+ * can disclose it instead of showing nothing.
+ */
+export declare type ResolvedList = {
+    kind: 'values';
+    values: string[];
+} | {
+    kind: 'formula';
+    formula: string;
+};
+
 export declare interface Row {
     index: number;
     height: number | null;
@@ -1046,6 +1084,17 @@ export declare interface Worksheet {
     /** A1-style cell refs of commented cells (ECMA-376 §18.7.3). Rendered as a
      *  small red triangle in each cell's top-right corner. */
     commentRefs?: string[];
+    /** Full-fidelity comment bodies (cell ref + author + plain text) for every
+     *  `<comment>` in `xl/commentsN.xml` (ECMA-376 §18.7). Parallel to
+     *  {@link commentRefs} (one entry per ref). Consume this to read the note
+     *  text; the renderer uses {@link commentRefs} for the red indicator and the
+     *  viewer surfaces these bodies in an Excel-style hover popup. */
+    comments?: XlsxComment[];
+    /** Data-validation rules on this sheet (ECMA-376 §18.3.1.32–33). Exposed for
+     *  tooling. The viewer draws a list-dropdown arrow on the active cell when the
+     *  selection intersects a `list`-type rule's `sqref` (display only — opening
+     *  the list / picking a value is out of scope for a viewer). */
+    dataValidations?: DataValidation[];
     /** Defined names in scope for this sheet (ECMA-376 §18.2.5). Used by
      *  conditional-formatting `expression` rules that call named ranges
      *  (e.g. `task_start`, `today`). */
@@ -1118,6 +1167,24 @@ export declare interface XlsxChartSeries {
     errBars?: ErrBars[];
 }
 
+/** One cell comment. Sourced from the classic notes file `xl/commentsN.xml`
+ *  (ECMA-376 §18.7) when present, otherwise from the Office-365 threaded
+ *  comments part `xl/threadedComments/` (MS-XLSX schema
+ *  `…/spreadsheetml/2018/threadedcomments`, `personId` resolved via
+ *  `xl/persons/`). `text` is the joined plain text — every `<r><t>` run for
+ *  classic notes, every reply in the thread (newline-joined) for threaded
+ *  comments; rich-text formatting is dropped. 1:1 with the Rust `XlsxComment`
+ *  (serde camelCase). */
+export declare interface XlsxComment {
+    /** A1-style cell reference (`@ref` on the comment element). */
+    cellRef: string;
+    /** Resolved author name — the `<authors>` entry (classic) or the `<person>`
+     *  `displayName` (threaded). Absent when unresolved. */
+    author?: string;
+    /** Concatenated plain text of every run / threaded reply. */
+    text: string;
+}
+
 /** Emitted once per cell that has text, with the cell's canvas-pixel bounds. */
 export declare interface XlsxTextRunInfo {
     text: string;
@@ -1171,6 +1238,32 @@ export declare class XlsxViewer {
     private selectionOverlay;
     private keydownHandler;
     private pendingTap;
+    /** DOM overlay element that shows the hovered cell's comment. Lives in
+     *  canvasArea above the scrollHost; `pointer-events:none` so it never blocks
+     *  cell interaction. */
+    private commentPopup;
+    /** `"row:col"` → comment for the current sheet, rebuilt on every showSheet. */
+    private commentMap;
+    /** `"row:col"` of the cell whose popup is currently shown (or pending), so a
+     *  pointermove within the same cell doesn't restart the show timer. */
+    private commentPopupKey;
+    /** Pending show timer (see {@link COMMENT_POPUP_DELAY_MS}). */
+    private commentPopupTimer;
+    /** DOM overlay listing a list-validated cell's allowed values. Lives in
+     *  canvasArea above the scrollHost; unlike the comment popup this is a click
+     *  target (`pointer-events:auto`). Read-only: hovering an item highlights it
+     *  but selecting does NOT change the cell. */
+    private validationPanel;
+    /** `"row:col"` of the cell whose panel is currently open, or null. Lets a
+     *  re-click on the same arrow toggle the panel closed. */
+    private validationPanelKey;
+    /** Screen rect (canvasArea CSS px) of the dropdown arrow button last drawn by
+     *  {@link maybeDrawValidationDropdown}, so pointerdown can hit-test it. Null
+     *  when no arrow is currently visible. */
+    private validationArrowRect;
+    /** Document-level pointerdown listener that closes the panel on an outside
+     *  click; installed only while the panel is open. */
+    private validationOutsideHandler;
     constructor(container: HTMLElement, opts?: XlsxViewerOptions);
     /**
      * Load an XLSX from URL or ArrayBuffer and render the first sheet.
@@ -1245,6 +1338,14 @@ export declare class XlsxViewer {
     private getCellRect;
     /** Returns the current selection, including mode. */
     get selection(): CellRange | null;
+    /**
+     * Programmatically select a single cell by A1 reference (e.g. `"B2"`), as if
+     * the user had clicked it: updates the active/anchor cell, redraws the
+     * selection overlay (including any list-validation dropdown arrow), and fires
+     * `onSelectionChange`. A no-op for malformed refs. Closes any open validation
+     * panel, matching the click path.
+     */
+    select(ref: string): void;
     /**
      * Returns what the header area contains at the given client coordinates.
      * Returns null when the point is in the cell grid (not a header).
@@ -1253,6 +1354,49 @@ export declare class XlsxViewer {
     /** Copy the selected cell range as tab-separated text to the clipboard. */
     private copySelection;
     private updateSelectionOverlay;
+    /** Draw the Excel list-validation dropdown button just outside the
+     *  bottom-right corner of the *active* cell when that cell is covered by a
+     *  `list` data-validation rule. Anchored to the single active cell (not the
+     *  whole range) to mirror Excel, which attaches the button to the active
+     *  cell of the selection. */
+    private maybeDrawValidationDropdown;
+    /** Toggle the dropdown panel for the active cell's list validation. Called
+     *  from pointerdown when the arrow rect is hit. Re-clicking the same arrow
+     *  closes it. */
+    private toggleValidationPanel;
+    /** Resolve the allowed values for `formula1` (relative to the current sheet)
+     *  and render them in the panel anchored below the active cell. Async because
+     *  cross-sheet range references may need a lazily-parsed worksheet. */
+    private openValidationPanel;
+    /** Build the panel's children. Uses textContent throughout (no HTML injection
+     *  from cell values). Items highlight on hover but are NOT selectable —
+     *  this is a read-only viewer, so clicking a value must not change the cell. */
+    private renderValidationPanel;
+    /** Position the (already-populated, visible-or-becoming-visible) panel below
+     *  the dropdown arrow / active cell using the pure geometry calculator. */
+    private positionValidationPanel;
+    /** Install a document-level pointerdown listener that closes the panel on a
+     *  click outside it (and outside the arrow, which toggles via its own path).
+     *  Removed by {@link hideValidationPanel}. */
+    private installValidationOutsideHandler;
+    /** Hide the panel and detach its outside-click listener. Called on re-click,
+     *  outside click, Esc, scroll, selection change, sheet switch and destroy. */
+    private hideValidationPanel;
+    /** Build the `"row:col"` → comment index for the given sheet. Parses each
+     *  `XlsxComment.cellRef` with the shared {@link parseA1}; later refs win on a
+     *  collision (Excel allows at most one note per cell, so this is moot in
+     *  practice). */
+    private buildCommentMap;
+    /** Show the popup for the comment on `cell` after the hover dwell, anchored to
+     *  the cell's current on-screen rect. No-op when the cell carries no comment.
+     *  Re-hovering the same cell does not restart the timer. */
+    private scheduleCommentPopup;
+    /** Immediately render the popup for `comment` anchored to `cell` (used by the
+     *  hover-dwell timer and by touch selection, which has no hover). */
+    private renderCommentPopup;
+    /** Hide the popup and cancel any pending show. Called on cell-out, scroll,
+     *  sheet switch and destroy. */
+    private hideCommentPopup;
     private applyPointerSelection;
     private setupSelectionEvents;
     private buildTabs;
@@ -1354,6 +1498,22 @@ export declare class XlsxWorkbook {
      *  `null` for sheets that declare no tab color. */
     get tabColors(): (string | null)[];
     getWorksheet(sheetIndex: number): Promise<Worksheet>;
+    /**
+     * Resolve a `list`-type data-validation `formula1` (ECMA-376 §18.3.1.32) into
+     * the set of allowed values to display, evaluated relative to `sheetIndex`
+     * (the sheet that owns the validation, used to resolve unqualified ranges):
+     *
+     * - Inline quoted list `"A,B,C"`        → the literal values.
+     * - Range ref `$B$2:$B$5`               → each non-empty cell's *display
+     *   string* (the same formatted text the grid shows, via {@link formatCellValue}),
+     *   walked row-major. `Sheet2!$A$1:$A$9` resolves against the named sheet
+     *   (lazily parsed via {@link getWorksheet}, hence async).
+     * - Named range / complex formula       → `{ kind: 'formula' }` carrying the
+     *   raw text so the caller can disclose it rather than blanking it.
+     *
+     * Read-only: this only reads cell values for display; it never writes.
+     */
+    resolveValidationList(sheetIndex: number, formula1: string | undefined): Promise<ResolvedList>;
     renderViewport(target: HTMLCanvasElement | OffscreenCanvas, sheetIndex: number, viewport: ViewportRange, opts?: RenderViewportOptions): Promise<void>;
     destroy(): void;
 }