@silurus/ooxml 0.55.0 → 0.57.0

package/dist/types/xlsx.d.ts

@@ -131,12 +131,12 @@ export declare interface CellXf {
     readingOrder?: number;
 }
 
-declare interface CfIcon {
+export declare interface CfIcon {
     iconSet: string;
     iconId: number;
 }
 
-declare type CfRule = {
+export declare type CfRule = {
     type: 'cellIs';
     operator: string;
     formulas: string[];
@@ -184,18 +184,18 @@ declare type CfRule = {
     priority: number;
 };
 
-declare interface CfStop {
+export declare interface CfStop {
     kind: string;
     value: string | null;
     color: string;
 }
 
-declare interface CfValue {
+export declare interface CfValue {
     kind: string;
     value: string | null;
 }
 
-declare interface ChartAnchor {
+export declare interface ChartAnchor {
     fromCol: number;
     fromColOff: number;
     fromRow: number;
@@ -212,7 +212,7 @@ declare interface ChartAnchor {
  * which the renderer combines into a canonical `ChartModel.chartType` (e.g.
  * `clusteredBarH`, `stackedBarPct`) at render time.
  */
-declare interface ChartData {
+export declare interface ChartData {
     /** Primary chart type: "bar"|"line"|"area"|"pie"|"doughnut"|"radar"|"scatter" */
     chartType: string;
     /** "col" (vertical bars) | "row" (horizontal bars) */
@@ -321,12 +321,12 @@ declare interface ChartData {
     plotAreaManualLayout?: ManualLayout;
 }
 
-declare interface ConditionalFormat {
+export declare interface ConditionalFormat {
     sqref: CellRange_2[];
     rules: CfRule[];
 }
 
-declare interface DataLabelOverride {
+export declare interface DataLabelOverride {
     idx: number;
     text: string;
     /** "l"|"r"|"t"|"b"|"ctr"|"outEnd"|"bestFit" or undefined → inherit. */
@@ -336,7 +336,7 @@ declare interface DataLabelOverride {
     fontBold?: boolean;
 }
 
-declare interface DataPointOverride {
+export declare interface DataPointOverride {
     idx: number;
     color?: string;
     markerSymbol?: string;
@@ -345,12 +345,12 @@ declare interface DataPointOverride {
     markerLine?: string;
 }
 
-declare interface DefinedName {
+export declare interface DefinedName {
     name: string;
     formula: string;
 }
 
-declare interface Dxf {
+export declare interface Dxf {
     font: CellFont | null;
     fill: CellFill | null;
     border: Border | null;
@@ -361,7 +361,7 @@ declare interface Dxf {
     numFmt?: NumFmt | null;
 }
 
-declare interface ErrBars {
+export declare interface ErrBars {
     /** "x" | "y". */
     dir: string;
     /** "plus" | "minus" | "both". */
@@ -375,7 +375,7 @@ declare interface ErrBars {
     dash?: string;
 }
 
-declare interface GradientFillSpec {
+export declare interface GradientFillSpec {
     /** "linear" (default) or "path". */
     gradientType: string;
     /** Rotation in degrees for linear gradients (0 = left→right). */
@@ -391,7 +391,7 @@ declare interface GradientFillSpec {
     }[];
 }
 
-declare interface Hyperlink {
+export declare interface Hyperlink {
     col: number;
     row: number;
     url: string | null;
@@ -401,7 +401,7 @@ declare interface Hyperlink {
  * Image anchored to a rectangle of cells (EMU offsets within the anchor cells).
  * 914400 EMU = 1 inch, 9525 EMU = 1 px @ 96 DPI.
  */
-declare interface ImageAnchor {
+export declare interface ImageAnchor {
     fromCol: number;
     fromColOff: number;
     fromRow: number;
@@ -423,7 +423,7 @@ declare interface ImageAnchor {
     dataUrl: string;
 }
 
-declare interface LegendManualLayout {
+export declare interface LegendManualLayout {
     xMode: string;
     yMode: string;
     x: number;
@@ -476,7 +476,7 @@ declare interface LoadOptions_2 {
     math?: MathRenderer;
 }
 
-declare interface ManualLayout {
+export declare interface ManualLayout {
     xMode: string;
     yMode: string;
     layoutTarget?: string;
@@ -637,7 +637,7 @@ export declare interface ParsedWorkbook {
     sharedStrings: SharedString[];
 }
 
-declare type PathCmd = {
+export declare type PathCmd = {
     op: 'moveTo';
     x: number;
     y: number;
@@ -672,7 +672,7 @@ declare type PathCmd = {
     op: 'close';
 };
 
-declare interface PathInfo {
+export declare interface PathInfo {
     w: number;
     h: number;
     commands: PathCmd[];
@@ -716,12 +716,12 @@ export declare interface Row {
     cells: Cell[];
 }
 
-declare interface Run {
+export declare interface Run {
     text: string;
     font?: RunFont;
 }
 
-declare interface RunFont {
+export declare interface RunFont {
     bold: boolean;
     italic: boolean;
     underline: boolean;
@@ -745,7 +745,7 @@ declare interface RunFont {
 declare type SelectionMode_2 = 'cells' | 'rows' | 'cols' | 'all';
 export { SelectionMode_2 as SelectionMode }
 
-declare interface SeriesDataLabels {
+export declare interface SeriesDataLabels {
     showVal: boolean;
     showCatName: boolean;
     showSerName: boolean;
@@ -757,7 +757,7 @@ declare interface SeriesDataLabels {
     fontSizeHpt?: number;
 }
 
-declare interface ShapeAnchor {
+export declare interface ShapeAnchor {
     fromCol: number;
     fromColOff: number;
     fromRow: number;
@@ -778,9 +778,14 @@ declare interface ShapeAnchor {
     shapes: ShapeInfo[];
 }
 
-declare type ShapeGeom = {
+export declare type ShapeGeom = {
     type: 'preset';
     name: string;
+    /** Adjust handles from `<a:avLst><a:gd>` in `adj1..adj8` order
+     *  (ECMA-376 §19.5.31.3 / §20.1.9.5). `null` entries mean "use the
+     *  preset's declared default". Omitted entirely when the shape has no
+     *  `<a:avLst>`. Consumed by the shared `renderPresetShape` engine. */
+    adj?: (number | null)[];
 } | {
     type: 'custom';
     paths: PathInfo[];
@@ -793,7 +798,7 @@ declare type ShapeGeom = {
     dataUrl: string;
 };
 
-declare interface ShapeInfo {
+export declare interface ShapeInfo {
     /** Normalized [0,1] position/size relative to the anchor rect. */
     x: number;
     y: number;
@@ -811,13 +816,16 @@ declare interface ShapeInfo {
     text?: ShapeText;
 }
 
-declare interface ShapeParagraph {
+export declare interface ShapeParagraph {
     /** `<a:pPr@algn>` — `l` (default) | `ctr` | `r` | `just` | `dist`. */
     align: string;
+    /** `<a:pPr@rtl>` — whether the paragraph reads right-to-left
+     *  (ECMA-376 §21.1.2.2.7). Omitted (undefined) when false. */
+    rtl?: boolean;
     runs: ShapeTextRun[];
 }
 
-declare interface ShapeText {
+export declare interface ShapeText {
     /** `<a:bodyPr@anchor>` — vertical alignment of the text block within the
      *  shape rect. `t` (top, default), `ctr` (middle), `b` (bottom). */
     anchor: string;
@@ -830,7 +838,7 @@ declare interface ShapeText {
  *  (matches the pptx `TextRun` shape): styled text, a soft line break, or an
  *  OMML equation. Excel stores "Insert > Equation" as OMML inside the shared
  *  DrawingML `<xdr:txBody>` grammar (ECMA-376 §22.1), like PowerPoint. */
-declare type ShapeTextRun = {
+export declare type ShapeTextRun = {
     type: 'text';
     text: string;
     bold: boolean;
@@ -853,7 +861,7 @@ declare type ShapeTextRun = {
     color?: string;
 };
 
-declare interface SharedString {
+export declare interface SharedString {
     text: string;
     runs?: Run[];
 }
@@ -868,7 +876,7 @@ export declare interface SheetMeta {
     tabColor?: string | null;
 }
 
-declare interface SlicerAnchor {
+export declare interface SlicerAnchor {
     fromCol: number;
     fromColOff: number;
     fromRow: number;
@@ -881,12 +889,12 @@ declare interface SlicerAnchor {
     items: SlicerItem[];
 }
 
-declare interface SlicerItem {
+export declare interface SlicerItem {
     name: string;
     selected: boolean;
 }
 
-declare interface Sparkline {
+export declare interface Sparkline {
     /** 1-based row of the destination cell (`<xm:sqref>`). */
     row: number;
     /** 1-based column of the destination cell. */
@@ -896,7 +904,7 @@ declare interface Sparkline {
     values: (number | null)[];
 }
 
-declare interface SparklineGroup {
+export declare interface SparklineGroup {
     /** `line` (default) | `column` | `stem` (win-loss). */
     kind: 'line' | 'column' | 'stem';
     markers: boolean;
@@ -939,7 +947,7 @@ export declare interface Styles {
 
 /** Per-column DXF references inside a `<table>` element
  *  (ECMA-376 §18.5.1.3 `tableColumn`). */
-declare interface TableColumnInfo {
+export declare interface TableColumnInfo {
     /** `<tableColumn dataDxfId>` — applied to data cells in this column. */
     dataDxfId?: number;
     /** `<tableColumn headerRowDxfId>` — applied to the header cell of this column. */
@@ -948,7 +956,7 @@ declare interface TableColumnInfo {
     totalsRowDxfId?: number;
 }
 
-declare interface TableInfo {
+export declare interface TableInfo {
     range: CellRange_2;
     styleName: string;
     headerRowCount: number;
@@ -960,13 +968,29 @@ declare interface TableInfo {
     /** Accent color resolved by the parser from the built-in style name against
      *  the file's theme accents (e.g. `TableStyleLight18` → accent3). */
     accentColor: string;
+    /** `true` when `styleName` is defined in the file's `<tableStyles>` block,
+     *  i.e. a *custom* style (ECMA-376 §18.5.1.2). The renderer draws such tables
+     *  strictly from their declared element dxfs and must NOT apply the accent
+     *  approximation (banding / synthesized rules / header) reserved for built-in
+     *  style names whose definitions are absent from the file. */
+    isCustom?: boolean;
     /** Dxf index for the `wholeTable` element of a custom `<tableStyle>`
-     *  (ECMA-376 §18.8.40). When set, its border/fill apply to every cell of
+     *  (ECMA-376 §18.8.83). When set, its border/fill apply to every cell of
      *  the table as a base layer. Undefined for built-in style names. */
     wholeTableDxf?: number;
     /** Dxf index for the `headerRow` element of a custom `<tableStyle>` —
      *  provides header background, font color/weight, and vertical separators. */
     headerRowDxf?: number;
+    /** Dxf index for the `totalRow` element (ECMA-376 §18.18.93). */
+    totalRowDxf?: number;
+    /** Dxf index for the `firstColumn` element. */
+    firstColumnDxf?: number;
+    /** Dxf index for the `lastColumn` element. */
+    lastColumnDxf?: number;
+    /** Dxf index for `firstRowStripe` (band1 horizontal) — odd banded-row stripe. */
+    band1HorizontalDxf?: number;
+    /** Dxf index for `secondRowStripe` (band2 horizontal) — even banded-row stripe. */
+    band2HorizontalDxf?: number;
     /** Per-column DXF references (ECMA-376 §18.5.1.3 `tableColumn`). Index by
      *  `cellCol - range.left`. The renderer can use these to apply column-level
      *  overlays for named-style tables; for files where Excel pre-bakes the
@@ -1009,6 +1033,10 @@ export declare interface Worksheet {
      *  `<sheetView showGridLines>`). Mirrors the Excel "View → Gridlines"
      *  checkbox. Defaults to true. */
     showGridlines?: boolean;
+    /** Whether the sheet grid is laid out right-to-left, mirroring the entire
+     *  grid so column A sits on the right (ECMA-376 §18.3.1.87
+     *  `<sheetView rightToLeft>`). Defaults to false. */
+    rightToLeft?: boolean;
     /** Sheet tab color (ECMA-376 §18.3.1.79). */
     tabColor?: string | null;
     /** AutoFilter header range (ECMA-376 §18.3.1.2). */
@@ -1047,7 +1075,7 @@ export declare interface Worksheet {
  * XLSX parser's raw chart series (includes XLSX-only `seriesType` for mixed
  * charts). Adapted to `ChartSeries` from @silurus/ooxml-core before rendering.
  */
-declare interface XlsxChartSeries {
+export declare interface XlsxChartSeries {
     name: string;
     /** Chart sub-type for this series (allows mixed charts). */
     seriesType: string;
@@ -1125,6 +1153,17 @@ export declare class XlsxViewer {
     private currentWorksheet;
     private opts;
     private resizeObserver;
+    /**
+     * Start-anchored horizontal scroll position (the {@link effectiveScrollLeft}
+     * value last produced by a real user scroll or a programmatic reset), kept
+     * as the source of truth across container size changes. The native
+     * `scrollLeft` cannot serve that role for RTL sheets (ECMA-376 §18.3.1.87):
+     * it is the *inverse* of the start-anchored offset, and the browser clamps
+     * any assignment to 0 while the host is unlaid-out (`display:none` mount —
+     * e.g. a host revealed only after `load()` resolves), which would otherwise
+     * strand the view at the sheet's far end once the host gains its real size.
+     */
+    private effectiveH;
     private anchorCell;
     private activeCell;
     private selectionMode;
@@ -1144,6 +1183,45 @@ export declare class XlsxViewer {
     /** The loaded workbook, or throws if {@link load} has not completed. */
     private get workbook();
     showSheet(index: number): Promise<void>;
+    /** True when the current sheet's grid is laid out right-to-left. */
+    private get isRtl();
+    /** Maximum horizontal scroll offset the native scroll host allows (≥ 0). */
+    private get maxScrollLeft();
+    /**
+     * The logical horizontal scroll position used to find the start-of-sheet
+     * (col A) edge, in *scaled* CSS pixels — the same unit as
+     * `scrollHost.scrollLeft`. The renderer always lays the grid out LTR and then
+     * mirrors it (ECMA-376 §18.3.1.87), so the viewer must hand it a position
+     * where 0 = the START of the sheet (col A) and increasing values reveal later
+     * columns.
+     *
+     * For LTR that is exactly the native `scrollLeft`. For RTL the sheet starts at
+     * the RIGHT, so the native scrollbar runs the opposite way: thumb fully right
+     * (`scrollLeft = maxScrollLeft`) is the start, thumb left is the far columns.
+     * Inverting here makes wheel/trackpad follow the finger and aligns the
+     * thumb↔page mapping with Excel, without depending on browser-specific RTL
+     * `scrollLeft` sign conventions.
+     */
+    private get effectiveScrollLeft();
+    /**
+     * Map between the logical-LTR x used by all the cell-geometry math and the
+     * on-screen (canvasArea CSS-pixel) x, applying the RTL mirror (ECMA-376
+     * §18.3.1.87) via the same {@link rtlMirrorX} the renderer uses. For LTR this
+     * is the identity. The mirror is an involution, so this one method serves
+     * both cell→px (overlay draw, `w` = cell width) and px→cell (pointer
+     * hit-testing, `w` = 0 for a point) — guaranteeing the overlay sits exactly
+     * where the cell is drawn and a click resolves to that same cell at every
+     * scroll offset. `canvasArea.clientWidth` equals the renderer's `canvasW`.
+     */
+    private screenX;
+    /** Park the scrollbar at the sheet's natural start: scrollLeft=0 for LTR,
+     *  the right end for RTL (so col A shows first). */
+    private resetHorizontalScroll;
+    /** Re-derive the native scrollLeft from the tracked start-anchored
+     *  position after the scroll host's size changes. Only RTL needs this:
+     *  for LTR the native scrollLeft *is* start-anchored and the browser
+     *  already clamps it sensibly on resize. */
+    private reanchorHorizontalScroll;
     /** 0-based index of the currently displayed sheet. */
     get sheetIndex(): number;
     /** Total number of sheets in the loaded workbook. */
@@ -1217,7 +1295,15 @@ export declare interface XlsxViewerOptions {
     zoomMin?: number;
     zoomMax?: number;
     onReady?: (sheetNames: string[]) => void;
-    onSheetChange?: (index: number, name: string) => void;
+    /**
+     * Called when the active sheet changes, with the new sheet's zero-based
+     * `index` and the `total` number of sheets in the workbook. This mirrors the
+     * docx `onPageChange` and pptx `onSlideChange` contracts so all three viewers
+     * share one callback shape. To get the sheet *name*, look it up by index from
+     * `viewer.sheetNames[index]` (or the `sheetNames` array delivered to
+     * `onReady`).
+     */
+    onSheetChange?: (index: number, total: number) => void;
     onError?: (err: Error) => void;
     /** Called when the selected cell range changes. null means no selection. */
     onSelectionChange?: (selection: CellRange | null) => void;