@lotics/xlsx 0.1.0

package/src/types.ts

@@ -0,0 +1,239 @@
+import type { ParsedConditionalFormat } from "./excel_cf_types";
+import type {
+  ParsedChart,
+  ParsedTable,
+  ParsedDrawing,
+  ParsedSparklineGroup,
+  AutoFilterRange,
+  ParsedDataValidation,
+} from "./ooxml_chart_types";
+import type { ParsedPivotCache, ParsedPivotTable } from "./ooxml_pivot_types";
+
+// =============================================================================
+// Core spreadsheet types
+// =============================================================================
+
+export interface ParsedSpreadsheet {
+  sheets: ParsedSheet[];
+  activeSheetIndex: number;
+  namedRanges?: Map<string, string>;
+  /**
+   * Workbook's `calcPr.fullCalcOnLoad` flag. When true, consumers that
+   * render cells must recompute every formula before trusting the cached
+   * value — Excel does this automatically; our renderer needs to opt in.
+   */
+  fullCalcOnLoad?: boolean;
+  /**
+   * Workbook-level pivot caches keyed by `cacheId`. Multiple pivot tables
+   * may share a cache.
+   */
+  pivotCaches?: Map<number, ParsedPivotCache>;
+}
+
+export interface ParsedSheet {
+  name: string;
+  /** True when the sheet is hidden/veryHidden in the workbook. Renderers skip
+   * these; data consumers may still read them. */
+  hidden?: boolean;
+  columns: ParsedColumn[];
+  rows: ParsedRow[];
+  mergedCells: MergedCellRange[];
+  totalRowCount: number;
+  truncated: boolean;
+  defaultRowHeight: number;
+  defaultColWidth: number;
+  showGridLines: boolean;
+  freezePane?: FreezePane;
+  conditionalFormats: ParsedConditionalFormat[];
+  images: ParsedImage[];
+  rowOutlineLevels: Map<number, number>;
+  colOutlineLevels: Map<number, number>;
+  charts?: ParsedChart[];
+  tables?: ParsedTable[];
+  drawings?: ParsedDrawing[];
+  /** Pivot tables placed on this sheet. Cache lookups go through `ParsedSpreadsheet.pivotCaches`. */
+  pivotTables?: ParsedPivotTable[];
+  dataValidations?: ParsedDataValidation[];
+  sparklineGroups?: ParsedSparklineGroup[];
+  autoFilter?: AutoFilterRange;
+  rowPageBreaks?: number[];
+  colPageBreaks?: number[];
+  pageSetup?: PageSetup;
+  printTitles?: PrintTitles;
+  headerFooter?: HeaderFooter;
+}
+
+export interface ParsedImage {
+  dataUrl: string;
+  tl: { row: number; col: number };
+  br: { row: number; col: number };
+}
+
+export interface FreezePane {
+  frozenRows: number;
+  frozenCols: number;
+}
+
+/**
+ * Page setup for printing / PDF export. Applied per-sheet.
+ * `paperSize` is the OOXML numeric code (9 = A4, 1 = Letter).
+ * `fitToWidth`/`fitToHeight` = 0 disables that dimension's fit.
+ */
+export interface PageSetup {
+  orientation?: "portrait" | "landscape";
+  paperSize?: number;
+  fitToWidth?: number;
+  fitToHeight?: number;
+  scale?: number;
+  margins?: {
+    left?: number;
+    right?: number;
+    top?: number;
+    bottom?: number;
+    header?: number;
+    footer?: number;
+  };
+}
+
+/**
+ * Rows and/or columns to repeat on every printed page. Rows/cols are
+ * 1-indexed inclusive ranges. `repeatRows: [1, 1]` repeats only row 1.
+ */
+export interface PrintTitles {
+  repeatRows?: [number, number];
+  repeatCols?: [number, number];
+}
+
+/**
+ * Page header/footer text. Supports Excel field codes:
+ * `&P` page, `&N` pages, `&F` file, `&A` sheet, `&D` date, `&T` time,
+ * `&L`/`&C`/`&R` left/center/right sections.
+ */
+export interface HeaderFooter {
+  oddHeader?: string;
+  oddFooter?: string;
+  evenHeader?: string;
+  evenFooter?: string;
+  firstHeader?: string;
+  firstFooter?: string;
+  differentOddEven?: boolean;
+  differentFirst?: boolean;
+}
+
+export interface ParsedColumn {
+  index: number;
+  width: number;
+  hidden: boolean;
+}
+
+export interface ParsedRow {
+  index: number;
+  height: number;
+  cells: ParsedCell[];
+  hidden: boolean;
+}
+
+export type CellContent =
+  | { type: "plain"; text: string }
+  | { type: "rich_text"; parts: RichTextPart[] }
+  | { type: "hyperlink"; text: string; url: string; tooltip?: string };
+
+export interface RichTextPart {
+  text: string;
+  font?: RichTextFont;
+}
+
+export interface RichTextFont {
+  bold?: boolean;
+  italic?: boolean;
+  color?: string;
+  size?: number;
+  name?: string;
+  underline?: "single" | "double";
+  strike?: boolean;
+  vertAlign?: "superscript" | "subscript";
+}
+
+export interface ParsedCell {
+  column: number;
+  value: string;
+  /** Raw numeric value for CF evaluation (avoids parseFloat on formatted display strings). */
+  rawValue?: number;
+  /** Typed cell value preserved from OOXML parsing for lossless round-trip export. */
+  typedValue?: string | number | boolean | null;
+  /** Number format code from the cell's style (e.g., "#,##0.00", "dd/mm/yyyy"). */
+  numFmtCode?: string;
+  /** Error code for error cells (e.g., "#DIV/0!", "#REF!", "#N/A"). */
+  error?: string;
+  content: CellContent;
+  style: CellStyle;
+  /**
+   * Original `s=` xf index from the source `xl/styles.xml` cellXfs table.
+   * Preserved by the parser so that the writer can passthrough the original
+   * styles part when nothing has been mutated, avoiding a costly rebuild.
+   */
+  originalXfIndex?: number;
+  formula?: string;
+  isArrayFormula?: boolean;
+  arrayRange?: string;
+}
+
+export interface GradientData {
+  type: "linear" | "radial";
+  degree: number;
+  stops: { position: number; color: string }[];
+}
+
+export interface CellStyle {
+  fontBold?: boolean;
+  fontItalic?: boolean;
+  fontColor?: string;
+  fontSize?: number;
+  fontName?: string;
+  fontUnderline?: "single" | "double";
+  fontStrike?: boolean;
+  fontVertAlign?: "superscript" | "subscript";
+  backgroundColor?: string;
+  horizontalAlign?: "left" | "center" | "right";
+  verticalAlign?: "top" | "middle" | "bottom";
+  wrapText?: boolean;
+  indent?: number;
+  textRotation?: number | "vertical";
+  borderTop?: BorderStyle;
+  borderRight?: BorderStyle;
+  borderBottom?: BorderStyle;
+  borderLeft?: BorderStyle;
+  backgroundGradient?: string;
+  backgroundPattern?: string;
+  gradientData?: GradientData;
+  patternType?: string;
+  shrinkToFit?: boolean;
+  borderDiagonal?: BorderStyle;
+  diagonalUp?: boolean;
+  diagonalDown?: boolean;
+  readingOrder?: number;
+}
+
+export interface BorderStyle {
+  width: number;
+  style: string;
+  color?: string;
+}
+
+export interface MergedCellRange {
+  startRow: number;
+  startCol: number;
+  endRow: number;
+  endCol: number;
+}
+
+// =============================================================================
+// Errors
+// =============================================================================
+
+export class PasswordProtectedError extends Error {
+  constructor() {
+    super("This file is password-protected and cannot be previewed");
+    this.name = "PasswordProtectedError";
+  }
+}