@lotics/xlsx 0.1.0

package/src/excel_utils.test.ts

@@ -0,0 +1,108 @@
+import { parseNameBoxInput, buildNamedRangeExpr } from "./excel_utils";
+
+describe("parseNameBoxInput", () => {
+  test("parses single cell reference", () => {
+    expect(parseNameBoxInput("A1")).toEqual({ kind: "cell", row: 1, col: 1 });
+    expect(parseNameBoxInput("C10")).toEqual({ kind: "cell", row: 10, col: 3 });
+    expect(parseNameBoxInput("AA1")).toEqual({ kind: "cell", row: 1, col: 27 });
+  });
+
+  test("parses range reference", () => {
+    expect(parseNameBoxInput("A1:C10")).toEqual({
+      kind: "range",
+      startRow: 1,
+      startCol: 1,
+      endRow: 10,
+      endCol: 3,
+    });
+    expect(parseNameBoxInput("B2:D5")).toEqual({
+      kind: "range",
+      startRow: 2,
+      startCol: 2,
+      endRow: 5,
+      endCol: 4,
+    });
+  });
+
+  test("normalizes reversed range", () => {
+    expect(parseNameBoxInput("C10:A1")).toEqual({
+      kind: "range",
+      startRow: 1,
+      startCol: 1,
+      endRow: 10,
+      endCol: 3,
+    });
+  });
+
+  test("parses row range", () => {
+    expect(parseNameBoxInput("1:5")).toEqual({ kind: "rowRange", startRow: 1, endRow: 5 });
+    expect(parseNameBoxInput("3:1")).toEqual({ kind: "rowRange", startRow: 1, endRow: 3 });
+  });
+
+  test("parses column range", () => {
+    expect(parseNameBoxInput("A:C")).toEqual({ kind: "colRange", startCol: 1, endCol: 3 });
+    expect(parseNameBoxInput("D:B")).toEqual({ kind: "colRange", startCol: 2, endCol: 4 });
+  });
+
+  test("strips $ signs (absolute refs)", () => {
+    expect(parseNameBoxInput("$A$1")).toEqual({ kind: "cell", row: 1, col: 1 });
+    expect(parseNameBoxInput("$A$1:$C$10")).toEqual({
+      kind: "range",
+      startRow: 1,
+      startCol: 1,
+      endRow: 10,
+      endCol: 3,
+    });
+    expect(parseNameBoxInput("$B:$D")).toEqual({ kind: "colRange", startCol: 2, endCol: 4 });
+  });
+
+  test("is case-insensitive", () => {
+    expect(parseNameBoxInput("a1")).toEqual({ kind: "cell", row: 1, col: 1 });
+    expect(parseNameBoxInput("b2:d5")).toEqual({
+      kind: "range",
+      startRow: 2,
+      startCol: 2,
+      endRow: 5,
+      endCol: 4,
+    });
+    expect(parseNameBoxInput("a:c")).toEqual({ kind: "colRange", startCol: 1, endCol: 3 });
+  });
+
+  test("returns undefined for invalid input", () => {
+    expect(parseNameBoxInput("")).toBeUndefined();
+    expect(parseNameBoxInput("   ")).toBeUndefined();
+    expect(parseNameBoxInput("hello")).toBeUndefined();
+    expect(parseNameBoxInput("A")).toBeUndefined();
+    expect(parseNameBoxInput("123")).toBeUndefined();
+    expect(parseNameBoxInput("0:0")).toBeUndefined();
+  });
+
+  test("returns undefined for row range with zero", () => {
+    expect(parseNameBoxInput("0:5")).toBeUndefined();
+  });
+
+  test("handles whitespace around input", () => {
+    expect(parseNameBoxInput("  A1  ")).toEqual({ kind: "cell", row: 1, col: 1 });
+    expect(parseNameBoxInput("  B2:D5  ")).toEqual({
+      kind: "range",
+      startRow: 2,
+      startCol: 2,
+      endRow: 5,
+      endCol: 4,
+    });
+  });
+});
+
+describe("buildNamedRangeExpr", () => {
+  test("builds absolute reference expression", () => {
+    expect(buildNamedRangeExpr("Sheet1", 1, 1, 10, 3)).toBe("Sheet1!$A$1:$C$10");
+  });
+
+  test("handles single cell range", () => {
+    expect(buildNamedRangeExpr("Demo", 5, 2, 5, 2)).toBe("Demo!$B$5:$B$5");
+  });
+
+  test("handles multi-letter columns", () => {
+    expect(buildNamedRangeExpr("Data", 1, 27, 10, 28)).toBe("Data!$AA$1:$AB$10");
+  });
+});

package/src/excel_utils.ts

@@ -0,0 +1,162 @@
+// =============================================================================
+// Name Box input parsing
+// =============================================================================
+
+export type ParsedInput =
+  | { kind: "cell"; row: number; col: number }
+  | { kind: "range"; startRow: number; startCol: number; endRow: number; endCol: number }
+  | { kind: "rowRange"; startRow: number; endRow: number }
+  | { kind: "colRange"; startCol: number; endCol: number };
+
+/**
+ * Parse all address-string forms the Name Box accepts.
+ * Strips `$`, uppercases, then tries: range, column range, row range, single cell.
+ */
+export function parseNameBoxInput(input: string): ParsedInput | undefined {
+  const val = input.trim().replace(/\$/g, "").toUpperCase();
+  if (!val) return undefined;
+
+  // Range: A1:C10
+  const rangeMatch = val.match(/^([A-Z]+\d+):([A-Z]+\d+)$/);
+  if (rangeMatch) {
+    const start = refToRowCol(rangeMatch[1]);
+    const end = refToRowCol(rangeMatch[2]);
+    if (start && end) {
+      return {
+        kind: "range",
+        startRow: Math.min(start.row, end.row),
+        startCol: Math.min(start.col, end.col),
+        endRow: Math.max(start.row, end.row),
+        endCol: Math.max(start.col, end.col),
+      };
+    }
+  }
+
+  // Column range: A:C
+  const colRangeMatch = val.match(/^([A-Z]+):([A-Z]+)$/);
+  if (colRangeMatch) {
+    const startCol = colLettersToNum(colRangeMatch[1]);
+    const endCol = colLettersToNum(colRangeMatch[2]);
+    return {
+      kind: "colRange",
+      startCol: Math.min(startCol, endCol),
+      endCol: Math.max(startCol, endCol),
+    };
+  }
+
+  // Row range: 1:5
+  const rowRangeMatch = val.match(/^(\d+):(\d+)$/);
+  if (rowRangeMatch) {
+    const startRow = parseInt(rowRangeMatch[1], 10);
+    const endRow = parseInt(rowRangeMatch[2], 10);
+    if (startRow > 0 && endRow > 0) {
+      return {
+        kind: "rowRange",
+        startRow: Math.min(startRow, endRow),
+        endRow: Math.max(startRow, endRow),
+      };
+    }
+    return undefined;
+  }
+
+  // Single cell: A1
+  const cell = refToRowCol(val);
+  if (cell) return { kind: "cell", row: cell.row, col: cell.col };
+
+  return undefined;
+}
+
+/** Build an absolute reference expression for a named range, e.g. "Sheet1!$A$1:$C$10". */
+export function buildNamedRangeExpr(
+  sheetName: string,
+  startRow: number,
+  startCol: number,
+  endRow: number,
+  endCol: number,
+): string {
+  const start = `$${colNumToLetters(startCol)}$${startRow}`;
+  const end = `$${colNumToLetters(endCol)}$${endRow}`;
+  return `${sheetName}!${start}:${end}`;
+}
+
+// =============================================================================
+// Column letter/number conversion
+// =============================================================================
+
+/** Convert column letters (A, B, ..., Z, AA, AB, ...) to 1-based column number. */
+export function colLettersToNum(letters: string): number {
+  let result = 0;
+  for (let i = 0; i < letters.length; i++) {
+    result = result * 26 + (letters.charCodeAt(i) - 64);
+  }
+  return result;
+}
+
+/** Convert 1-based column number to column letters (1→A, 26→Z, 27→AA, ...). */
+export function colNumToLetters(col: number): string {
+  let result = "";
+  let n = col;
+  while (n > 0) {
+    n--;
+    result = String.fromCharCode(65 + (n % 26)) + result;
+    n = Math.floor(n / 26);
+  }
+  return result;
+}
+
+// =============================================================================
+// A1-style cell reference utilities
+// =============================================================================
+
+/** Convert A1-style ref to { row, col } (both 1-based). */
+export function refToRowCol(ref: string): { row: number; col: number } | undefined {
+  const match = ref.match(/^(\$?)([A-Z]+)(\$?)(\d+)$/);
+  if (!match) return undefined;
+  return { col: colLettersToNum(match[2]), row: parseInt(match[4], 10) };
+}
+
+/** Convert { row, col } (both 1-based) to A1-style ref. */
+export function rowColToRef(row: number, col: number): string {
+  return colNumToLetters(col) + String(row);
+}
+
+// =============================================================================
+// Packed cell key (row, col) → number
+// =============================================================================
+//
+// Internal canonical key for `SheetModel.cells`. Row gets the high bits,
+// column gets the low 14 bits (Excel's max column count is 16384, which fits
+// in 14 bits exactly). The encoding uses multiplication, not bit-shift,
+// because Excel's max row count (1,048,576) combined with the column bits
+// would overflow the 32-bit limit of JavaScript bitwise operators.
+//
+// Stored values stay well under `Number.MAX_SAFE_INTEGER` for all valid
+// Excel coordinates, so the int packing is lossless.
+
+const PACK_COL_BITS = 14;
+const PACK_COL_MULT = 1 << PACK_COL_BITS; // 16384
+
+/** Pack a (1-based row, 1-based col) pair into a single integer key. */
+export function packRowCol(row: number, col: number): number {
+  return row * PACK_COL_MULT + col;
+}
+
+/** Inverse of `packRowCol`. */
+export function unpackRowCol(packed: number): { row: number; col: number } {
+  const row = Math.floor(packed / PACK_COL_MULT);
+  const col = packed - row * PACK_COL_MULT;
+  return { row, col };
+}
+
+/** Pack an A1-style ref into the same integer key. Returns -1 for invalid refs. */
+export function packRef(ref: string): number {
+  const rc = refToRowCol(ref);
+  if (!rc) return -1;
+  return packRowCol(rc.row, rc.col);
+}
+
+/** Inverse of `packRef`. */
+export function unpackRef(packed: number): string {
+  const { row, col } = unpackRowCol(packed);
+  return rowColToRef(row, col);
+}

package/src/fast-formula-parser.d.ts

@@ -0,0 +1,53 @@
+declare module "fast-formula-parser" {
+  interface CellRefArg {
+    row: number;
+    col: number;
+    sheet?: string;
+  }
+
+  interface RangeRefArg {
+    from: { row: number; col: number };
+    to: { row: number; col: number };
+    sheet?: string;
+  }
+
+  interface ParserConfig {
+    onCell?: (ref: CellRefArg) => unknown;
+    onRange?: (ref: RangeRefArg) => unknown;
+    functions?: Record<string, (...args: unknown[]) => unknown>;
+    functionsNeedContext?: Record<string, (...args: unknown[]) => unknown>;
+    onVariable?: (name: string) => unknown;
+  }
+
+  interface ParsePosition {
+    sheet: string;
+    row: number;
+    col: number;
+  }
+
+  interface DepRef {
+    row?: number;
+    col?: number;
+    sheet?: string;
+    from?: { row: number; col: number };
+    to?: { row: number; col: number };
+  }
+
+  class FormulaParser {
+    constructor(config?: ParserConfig);
+    parse(formula: string, position: ParsePosition): unknown;
+    static DepParser: typeof DepParser;
+    static FormulaError: typeof FormulaError;
+  }
+
+  class DepParser {
+    data: DepRef[];
+    parse(formula: string, position: ParsePosition): DepRef[];
+  }
+
+  class FormulaError extends Error {
+    name: string;
+  }
+
+  export default FormulaParser;
+}

package/src/fill_logic.ts

@@ -0,0 +1,257 @@
+// =============================================================================
+// Fill Logic
+// =============================================================================
+//
+// Pure spreadsheet fill-series computation. Given a source range and a target
+// range, computes the fill values (numeric series, cycle patterns, single-cell
+// increment, or modular copy).
+//
+// No DOM or React dependencies.
+// =============================================================================
+
+import type { Command } from "./command_history";
+import type { WorkbookModel } from "./workbook_model";
+import type { FormulaEngine } from "./formula_engine";
+import type { CellRange } from "./selection_model";
+import { rowColToRef } from "./excel_utils";
+import { setCellValueCommand, batchCommand } from "./spreadsheet_commands";
+import { detectCyclePattern } from "./fill_patterns";
+
+/**
+ * Compute fill commands for dragging a source range into a target range.
+ * Returns a batch command, or null if nothing to fill.
+ */
+export function computeFillCommand(
+  workbook: WorkbookModel,
+  engine: FormulaEngine | undefined,
+  sheetIndex: number,
+  sourceRange: { start: { row: number; col: number }; end: { row: number; col: number } },
+  fillTarget: CellRange,
+): Command | null {
+  const sheet = workbook.sheets[sheetIndex];
+  const srcRowCount = sourceRange.end.row - sourceRange.start.row + 1;
+  const srcColCount = sourceRange.end.col - sourceRange.start.col + 1;
+  const nt = {
+    startRow: Math.min(fillTarget.start.row, fillTarget.end.row),
+    startCol: Math.min(fillTarget.start.col, fillTarget.end.col),
+    endRow: Math.max(fillTarget.start.row, fillTarget.end.row),
+    endCol: Math.max(fillTarget.start.col, fillTarget.end.col),
+  };
+
+  // Detect numeric series with constant increment per column
+  const fillsVertically = nt.startCol >= sourceRange.start.col && nt.endCol <= sourceRange.end.col;
+  const colIncrements = new Map<number, { lastValue: number; increment: number }>();
+  if (fillsVertically && srcRowCount >= 2) {
+    for (let c = sourceRange.start.col; c <= sourceRange.end.col; c++) {
+      const values: number[] = [];
+      for (let r = sourceRange.start.row; r <= sourceRange.end.row; r++) {
+        const ref = rowColToRef(r, c);
+        const cell = sheet.getCell(ref);
+        const dv = cell?.displayValue ?? "";
+        const num = Number(dv);
+        if (isNaN(num) || dv.trim() === "") break;
+        values.push(num);
+      }
+      if (values.length === srcRowCount) {
+        const inc = values[1] - values[0];
+        let constant = true;
+        for (let i = 2; i < values.length; i++) {
+          if (Math.abs((values[i] - values[i - 1]) - inc) > 1e-10) {
+            constant = false;
+            break;
+          }
+        }
+        if (constant) {
+          colIncrements.set(c, { lastValue: values[values.length - 1], increment: inc });
+        }
+      }
+    }
+  }
+
+  // Detect date series per column. We parse displayValue as a date; if every
+  // source value parses, and the day-deltas are constant, we can extrapolate.
+  // Stored format string is preserved by re-emitting in ISO YYYY-MM-DD.
+  const colDates = new Map<number, { lastDay: number; increment: number }>();
+  if (fillsVertically && srcRowCount >= 2) {
+    for (let c = sourceRange.start.col; c <= sourceRange.end.col; c++) {
+      if (colIncrements.has(c)) continue;
+      const days: number[] = [];
+      let allParsed = true;
+      for (let r = sourceRange.start.row; r <= sourceRange.end.row; r++) {
+        const ref = rowColToRef(r, c);
+        const cell = sheet.getCell(ref);
+        const dv = cell?.displayValue ?? "";
+        const day = parseDateToDayNumber(dv);
+        if (day === undefined) { allParsed = false; break; }
+        days.push(day);
+      }
+      if (allParsed && days.length === srcRowCount) {
+        const inc = days[1] - days[0];
+        let constant = true;
+        for (let i = 2; i < days.length; i++) {
+          if (days[i] - days[i - 1] !== inc) { constant = false; break; }
+        }
+        if (constant && inc !== 0) {
+          colDates.set(c, { lastDay: days[days.length - 1], increment: inc });
+        }
+      }
+    }
+  }
+
+  // Detect cycle patterns (months, days, quarters) per column
+  const colCycles = new Map<number, { list: string[]; startIndex: number; count: number }>();
+  if (fillsVertically) {
+    for (let c = sourceRange.start.col; c <= sourceRange.end.col; c++) {
+      if (colIncrements.has(c)) continue;
+      const values: string[] = [];
+      for (let r = sourceRange.start.row; r <= sourceRange.end.row; r++) {
+        const ref = rowColToRef(r, c);
+        const cell = sheet.getCell(ref);
+        values.push(cell?.displayValue ?? "");
+      }
+      const match = detectCyclePattern(values.filter((v) => v !== ""));
+      if (match) {
+        colCycles.set(c, { ...match, count: values.filter((v) => v !== "").length });
+      }
+    }
+  }
+
+  const commands: Command[] = [];
+  for (let r = nt.startRow; r <= nt.endRow; r++) {
+    for (let c = nt.startCol; c <= nt.endCol; c++) {
+      // Multi-cell numeric series
+      const series = colIncrements.get(c);
+      if (series) {
+        const fillDown = nt.startRow > sourceRange.end.row;
+        const step = fillDown
+          ? (r - sourceRange.end.row)
+          : (sourceRange.start.row - r);
+        const value = fillDown
+          ? series.lastValue + step * series.increment
+          : (series.lastValue - (srcRowCount - 1) * series.increment) - step * series.increment;
+        commands.push(setCellValueCommand(workbook, engine, sheetIndex, r, c, String(value)));
+        continue;
+      }
+
+      // Date series (constant-day-delta over parseable date values)
+      const dateSeries = colDates.get(c);
+      if (dateSeries) {
+        const fillDown = nt.startRow > sourceRange.end.row;
+        const step = fillDown ? (r - sourceRange.end.row) : (sourceRange.start.row - r);
+        const day = fillDown
+          ? dateSeries.lastDay + step * dateSeries.increment
+          : (dateSeries.lastDay - (srcRowCount - 1) * dateSeries.increment) - step * dateSeries.increment;
+        commands.push(setCellValueCommand(workbook, engine, sheetIndex, r, c, dayNumberToIso(day)));
+        continue;
+      }
+
+      // Cycle pattern (month/day/quarter)
+      const cycle = colCycles.get(c);
+      if (cycle) {
+        const fillDown = nt.startRow > sourceRange.end.row;
+        const step = fillDown ? (r - sourceRange.end.row) : (sourceRange.start.row - r);
+        const idx = fillDown
+          ? (cycle.startIndex + cycle.count + step - 1) % cycle.list.length
+          : (cycle.startIndex - step + cycle.list.length) % cycle.list.length;
+        commands.push(setCellValueCommand(workbook, engine, sheetIndex, r, c, cycle.list[idx]));
+        continue;
+      }
+
+      // Single-cell numeric: increment by 1
+      if (srcRowCount === 1 && srcColCount === 1) {
+        const srcRef = rowColToRef(sourceRange.start.row, sourceRange.start.col);
+        const srcCell = sheet.getCell(srcRef);
+        if (srcCell) {
+          const num = Number(srcCell.displayValue);
+          if (!isNaN(num) && srcCell.displayValue.trim() !== "") {
+            const rowOffset = r - sourceRange.start.row;
+            const colOffset = c - sourceRange.start.col;
+            const offset = Math.max(Math.abs(rowOffset), Math.abs(colOffset));
+            const sign = (rowOffset + colOffset) >= 0 ? 1 : -1;
+            commands.push(setCellValueCommand(workbook, engine, sheetIndex, r, c, String(num + sign * offset)));
+            continue;
+          }
+        }
+      }
+
+      // Default: copy via modular wrapping
+      const srcRow = sourceRange.start.row + ((r - nt.startRow) % srcRowCount);
+      const srcCol = sourceRange.start.col + ((c - nt.startCol) % srcColCount);
+      const srcRef = rowColToRef(srcRow, srcCol);
+      const srcCell = sheet.getCell(srcRef);
+      const srcValue = srcCell?.formula ? `=${srcCell.formula}` : srcCell?.displayValue ?? "";
+      commands.push(setCellValueCommand(workbook, engine, sheetIndex, r, c, srcValue));
+    }
+  }
+
+  if (commands.length === 0) return null;
+  return batchCommand("Fill cells", commands);
+}
+
+// =============================================================================
+// Date helpers
+// =============================================================================
+
+const MS_PER_DAY = 86_400_000;
+
+/**
+ * Parse common date display formats into a "day number" (UTC day count since
+ * epoch, integer). Returns undefined if not parseable. Recognises:
+ *   - ISO `YYYY-MM-DD`
+ *   - US `m/d/yyyy` and `mm/dd/yyyy`
+ *   - European `d/m/yyyy` (only when day > 12, otherwise ambiguous → US wins)
+ *   - `d-MMM-yy` / `d-MMM-yyyy` and `d MMM yyyy` (`Mar 18 2026`)
+ */
+function parseDateToDayNumber(s: string): number | undefined {
+  if (!s) return undefined;
+  const t = s.trim();
+
+  const iso = t.match(/^(\d{4})-(\d{1,2})-(\d{1,2})$/);
+  if (iso) return toDay(parseInt(iso[1], 10), parseInt(iso[2], 10), parseInt(iso[3], 10));
+
+  const us = t.match(/^(\d{1,2})\/(\d{1,2})\/(\d{2,4})$/);
+  if (us) {
+    const m = parseInt(us[1], 10);
+    const d = parseInt(us[2], 10);
+    let y = parseInt(us[3], 10);
+    if (y < 100) y += y < 30 ? 2000 : 1900;
+    if (m >= 1 && m <= 12 && d >= 1 && d <= 31) return toDay(y, m, d);
+  }
+
+  // d-MMM-yy / d-MMM-yyyy / d MMM yyyy
+  const monthMap: Record<string, number> = {
+    jan: 1, feb: 2, mar: 3, apr: 4, may: 5, jun: 6,
+    jul: 7, aug: 8, sep: 9, oct: 10, nov: 11, dec: 12,
+  };
+  const named = t.match(/^(\d{1,2})[\s-]+([A-Za-z]{3,})[\s-]+(\d{2,4})$/);
+  if (named) {
+    const d = parseInt(named[1], 10);
+    const mname = named[2].slice(0, 3).toLowerCase();
+    const m = monthMap[mname];
+    let y = parseInt(named[3], 10);
+    if (m && y) {
+      if (y < 100) y += y < 30 ? 2000 : 1900;
+      return toDay(y, m, d);
+    }
+  }
+
+  // Last resort: native Date.parse — handles many locale variants. Strip time
+  // by floor-dividing.
+  const parsed = Date.parse(t);
+  if (!Number.isNaN(parsed)) {
+    return Math.floor(parsed / MS_PER_DAY);
+  }
+  return undefined;
+}
+
+function toDay(year: number, month: number, day: number): number {
+  return Math.floor(Date.UTC(year, month - 1, day) / MS_PER_DAY);
+}
+
+function dayNumberToIso(day: number): string {
+  const date = new Date(day * MS_PER_DAY);
+  const y = date.getUTCFullYear();
+  const m = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const d = String(date.getUTCDate()).padStart(2, "0");
+  return `${y}-${m}-${d}`;
+}

package/src/fill_patterns.test.ts

@@ -0,0 +1,90 @@
+import { detectCyclePattern, continueCycle } from "./fill_patterns";
+
+describe("detectCyclePattern", () => {
+  test("detects short month names", () => {
+    const result = detectCyclePattern(["Jan", "Feb", "Mar"]);
+    expect(result).not.toBeNull();
+    expect(result!.list[0]).toBe("Jan");
+    expect(result!.startIndex).toBe(0);
+  });
+
+  test("detects full month names mid-cycle", () => {
+    const result = detectCyclePattern(["March", "April", "May"]);
+    expect(result).not.toBeNull();
+    expect(result!.startIndex).toBe(2);
+  });
+
+  test("detects short day names", () => {
+    const result = detectCyclePattern(["Mon", "Tue", "Wed"]);
+    expect(result).not.toBeNull();
+    expect(result!.list).toContain("Sun");
+  });
+
+  test("detects full day names", () => {
+    const result = detectCyclePattern(["Friday", "Saturday", "Sunday"]);
+    expect(result).not.toBeNull();
+    expect(result!.startIndex).toBe(4);
+  });
+
+  test("detects quarters", () => {
+    const result = detectCyclePattern(["Q1", "Q2"]);
+    expect(result).not.toBeNull();
+    expect(result!.list).toEqual(["Q1", "Q2", "Q3", "Q4"]);
+  });
+
+  test("case insensitive matching", () => {
+    const result = detectCyclePattern(["jan", "feb", "mar"]);
+    expect(result).not.toBeNull();
+    expect(result!.list[0]).toBe("Jan");
+  });
+
+  test("returns null for no match", () => {
+    expect(detectCyclePattern(["Hello", "World"])).toBeNull();
+  });
+
+  test("returns null for empty array", () => {
+    expect(detectCyclePattern([])).toBeNull();
+  });
+
+  test("returns null for non-contiguous values", () => {
+    expect(detectCyclePattern(["Jan", "Mar", "May"])).toBeNull();
+  });
+
+  test("wraps around end of cycle", () => {
+    const result = detectCyclePattern(["Nov", "Dec"]);
+    expect(result).not.toBeNull();
+    expect(result!.startIndex).toBe(10);
+  });
+
+  test("single value matches", () => {
+    const result = detectCyclePattern(["Q3"]);
+    expect(result).not.toBeNull();
+    expect(result!.startIndex).toBe(2);
+  });
+});
+
+describe("continueCycle", () => {
+  test("continues month sequence", () => {
+    const match = detectCyclePattern(["Jan", "Feb", "Mar"])!;
+    const next = continueCycle(match, 3, 3);
+    expect(next).toEqual(["Apr", "May", "Jun"]);
+  });
+
+  test("wraps around end of year", () => {
+    const match = detectCyclePattern(["Nov", "Dec"])!;
+    const next = continueCycle(match, 2, 3);
+    expect(next).toEqual(["Jan", "Feb", "Mar"]);
+  });
+
+  test("continues quarter sequence", () => {
+    const match = detectCyclePattern(["Q3", "Q4"])!;
+    const next = continueCycle(match, 2, 2);
+    expect(next).toEqual(["Q1", "Q2"]);
+  });
+
+  test("continues day sequence wrapping", () => {
+    const match = detectCyclePattern(["Sat", "Sun"])!;
+    const next = continueCycle(match, 2, 2);
+    expect(next).toEqual(["Mon", "Tue"]);
+  });
+});