@opengeni/artifact-tool 0.2.2

package/src/spreadsheet-types.ts

@@ -0,0 +1,171 @@
+import type { RangeAddress } from "./spreadsheet-address";
+
+export type CellValue = string | number | boolean | Date | null;
+export type FormulaResult = CellValue | FormulaErrorValue;
+export type FormulaErrorValue =
+  | "#DIV/0!"
+  | "#N/A"
+  | "#NAME?"
+  | "#NUM!"
+  | "#REF!"
+  | "#VALUE!"
+  | "#CYCLE!";
+
+export type Color = string;
+export type FontConfig = {
+  name?: string;
+  size?: number;
+  bold?: boolean;
+  italic?: boolean;
+  underline?: boolean;
+  color?: Color;
+};
+export type BorderConfig = { style?: string; color?: Color; weight?: number };
+export type RangeBordersConfig = {
+  preset?: "none" | "outside" | "inside" | "all" | "doubleBottom";
+  style?: string;
+  color?: Color;
+  top?: BorderConfig;
+  bottom?: BorderConfig;
+  left?: BorderConfig;
+  right?: BorderConfig;
+  insideHorizontal?: BorderConfig;
+  insideVertical?: BorderConfig;
+};
+export type CellFormat = {
+  fill?: Color;
+  font?: FontConfig;
+  numberFormat?: string;
+  borders?: RangeBordersConfig;
+  horizontalAlignment?: "left" | "center" | "right" | "justify";
+  verticalAlignment?: "top" | "center" | "bottom";
+  wrapText?: boolean;
+};
+
+export type CellData = {
+  value: CellValue;
+  formula: string | null;
+  format: CellFormat;
+};
+
+export type FreezePaneState = { rows: number; columns: number };
+export type MergeRegion = RangeAddress;
+export type DataValidationConfig = { rule: Record<string, unknown> };
+export type ConditionalFormatConfig = Record<string, unknown>;
+
+export type SpreadsheetImageConfig = {
+  dataUrl?: string;
+  blob?: ArrayBuffer;
+  contentType?: string;
+  alt?: string;
+  anchor: {
+    from: { row: number; col: number; rowOffsetPx?: number; colOffsetPx?: number };
+    extent: { widthPx: number; heightPx: number };
+  };
+};
+
+export type SpreadsheetChartType =
+  | "bar"
+  | "line"
+  | "area"
+  | "pie"
+  | "doughnut"
+  | "scatter"
+  | "bubble"
+  | "radar"
+  | "stock"
+  | "treemap"
+  | "sunburst"
+  | "histogram"
+  | "boxWhisker"
+  | "waterfall"
+  | "funnel"
+  | "map";
+
+export type SpreadsheetChartSeriesConfig = {
+  name: string;
+  formula?: string;
+  categoryFormula?: string;
+  values?: number[];
+  categories?: Array<string | number>;
+  fill?: Color;
+};
+
+export type SpreadsheetChartConfig = {
+  chartType?: SpreadsheetChartType;
+  title?: string;
+  hasLegend?: boolean;
+  series?: SpreadsheetChartSeriesConfig[];
+};
+
+export type SpreadsheetSparklineType = "line" | "column" | "stacked";
+
+export type SpreadsheetSparklineMarkersOptions = {
+  show?: boolean;
+  high?: boolean;
+  low?: boolean;
+  first?: boolean;
+  last?: boolean;
+  negative?: boolean;
+};
+
+export type SpreadsheetSparklineAxisOptions = {
+  showAxis?: boolean;
+  manualMin?: number;
+  manualMax?: number;
+  rightToLeft?: boolean;
+};
+
+/** Style and display configuration shared by worksheet and range sparkline APIs. */
+export type SpreadsheetSparklineOptions = {
+  lineWeight?: number;
+  displayHidden?: boolean;
+  /** Skill-compatible proto enum: 0 = gaps, 1 = zero, 2 = connect. */
+  displayEmptyCellsAs?: 0 | 1 | 2;
+  seriesColor?: Color;
+  negativeColor?: Color;
+  axisColor?: Color;
+  markersColor?: Color;
+  firstMarkerColor?: Color;
+  lastMarkerColor?: Color;
+  highMarkerColor?: Color;
+  lowMarkerColor?: Color;
+  markers?: SpreadsheetSparklineMarkersOptions;
+  axis?: SpreadsheetSparklineAxisOptions;
+};
+
+export type InspectOptions = {
+  kind: string;
+  include?: string;
+  sheetId?: string;
+  range?: string;
+  search?: string;
+  maxChars?: number;
+  tableMaxRows?: number;
+  tableMaxCols?: number;
+  tableMaxCellChars?: number;
+  maxResults?: number;
+  options?: { maxResults?: number };
+  target?: { id: string; beforeLines?: number; afterLines?: number };
+};
+
+export type InspectResult = {
+  ndjson: string;
+  records: readonly Record<string, unknown>[];
+  truncated: boolean;
+};
+
+export type HelpOptions = {
+  search?: string;
+  include?: string;
+  maxChars?: number;
+};
+
+export type RenderSpreadsheetOptions = {
+  sheetName?: string;
+  range?: string;
+  autoCrop?: "all" | "content" | false;
+  scale?: number;
+  format?: "png" | "svg";
+  background?: string;
+};

package/src/spreadsheet-xlsx-api.ts

@@ -0,0 +1,123 @@
+export const XLSX_MEDIA_TYPE =
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" as const;
+
+export type SpreadsheetOpaqueRelationship = {
+  sourcePart: string;
+  type: string;
+  targetPart: string;
+};
+
+export type SpreadsheetOpaqueContentType = {
+  partName: string;
+  contentType: string;
+};
+
+/** Bounded, inert OOXML which is retained only in the original source package. */
+export type SpreadsheetOpaqueContent = {
+  parts: readonly string[];
+  relationships: readonly SpreadsheetOpaqueRelationship[];
+  contentTypes: readonly SpreadsheetOpaqueContentType[];
+  features: readonly string[];
+};
+
+export type SpreadsheetFidelityIssue = {
+  code:
+    | "content-preserved-in-source"
+    | "content-will-be-discarded"
+    | "editable-chart-preserved"
+    | "editable-chart-not-exportable"
+    | "sparkline-preserved"
+    | "sparkline-not-exportable"
+    | "image-metadata-not-exportable"
+    | "comment-thread-not-exportable";
+  severity: "warning" | "error";
+  feature: "opaque-ooxml" | "chart" | "sparkline" | "image" | "comment";
+  message: string;
+  parts?: readonly string[];
+  relationships?: readonly SpreadsheetOpaqueRelationship[];
+  contentTypes?: readonly SpreadsheetOpaqueContentType[];
+  features?: readonly string[];
+};
+
+export type SpreadsheetXlsxImportOptions = {
+  /** Reject unsupported editable OOXML instead of retaining its original package. */
+  unsupportedContent?: "preserve" | "error";
+  /** Bounded before ExcelJS allocates or parses any OOXML. */
+  limits?: Partial<SpreadsheetXlsxImportLimits>;
+};
+
+export type SpreadsheetXlsxImportLimits = {
+  compressedBytes: number;
+  expandedBytes: number;
+  entryBytes: number;
+  entries: number;
+  compressionRatio: number;
+  inspectedXmlBytes: number;
+  xmlDepth: number;
+  xmlAttributesPerElement: number;
+  xmlAttributesPerPart: number;
+  xmlAttributes: number;
+  xmlElementsPerPart: number;
+  xmlElements: number;
+  xmlTextCharactersPerPart: number;
+  xmlTextCharacters: number;
+  worksheetCellsPerPart: number;
+  worksheetCells: number;
+  formulasPerPart: number;
+  formulas: number;
+  formulaBytesPerPart: number;
+  formulaBytes: number;
+  sharedStrings: number;
+  cellStyles: number;
+  styleRecords: number;
+  commentsPerPart: number;
+  comments: number;
+  relationshipsPerPart: number;
+  relationships: number;
+  mediaEntries: number;
+  mediaEntryBytes: number;
+  mediaBytes: number;
+  imagePixels: number;
+};
+
+export type SpreadsheetLossPreservationEnvelope = {
+  version: 1;
+  mediaType: typeof XLSX_MEDIA_TYPE;
+  sourceBytes: Uint8Array;
+  sourceDigest: string;
+  opaqueContent: SpreadsheetOpaqueContent;
+  modelDigest: string;
+};
+
+export type SpreadsheetXlsxExportOptions = {
+  fileName?: string;
+  /** Must be explicit because ExcelJS cannot author every retained editable OOXML feature. */
+  unsupportedContent?: "error" | "discard";
+};
+
+export class SpreadsheetFidelityError extends Error {
+  readonly issues: readonly SpreadsheetFidelityIssue[];
+
+  constructor(message: string, issues: readonly SpreadsheetFidelityIssue[]) {
+    super(message);
+    this.name = "SpreadsheetFidelityError";
+    this.issues = issues;
+  }
+}
+
+export class SpreadsheetSecurityError extends Error {
+  constructor(
+    message: string,
+    readonly code:
+      | "invalid-package"
+      | "limit-exceeded"
+      | "encrypted-content"
+      | "active-content"
+      | "unsafe-xml"
+      | "external-relationship",
+    readonly entryName?: string,
+  ) {
+    super(message);
+    this.name = "SpreadsheetSecurityError";
+  }
+}