@shbernal/ts-xlsx 1.0.0

package/dist/core/cell.js

@@ -0,0 +1,249 @@
+// A single cell: a typed value at a fixed 1-based `(row, col)` position.
+//
+// Position is immutable and numeric — the corpus locks `col`/`row` as 1-based
+// *numbers* (legacy shipped a type declaration calling them strings, which broke
+// strict consumers). The value is the only mutable state here; assigning it routes
+// through the value model so the cell's `type` is always consistent with what it holds.
+import { encodeAddress } from "./address.js";
+import { NAMED_STYLE_ID } from "./internal.js";
+import { assignStyleFacets, } from "./style.js";
+import { coerceCellValue, detectValueType, } from "./value.js";
+/**
+ * A single cell owns its value and every style facet outright. Each facet below — fill, number format,
+ * font, border, alignment, protection, quote-prefix, and note — is held in the cell's own field and
+ * *replaced* (never mutated in place) by its setter, so a facet set on one cell never aliases or bleeds
+ * onto its row, column, or sheet siblings. Each facet's own doc covers only what is specific to it.
+ */
+export class Cell {
+    /** 1-based row index. */
+    row;
+    /** 1-based column index. */
+    col;
+    #value = null;
+    #fill;
+    #numFmt;
+    #font;
+    #border;
+    #alignment;
+    #protection;
+    #quotePrefix;
+    #namedStyleId;
+    #note;
+    constructor(row, col) {
+        if (!Number.isInteger(row) || row < 1) {
+            throw new RangeError(`cell row ${row} is out of bounds — rows start at 1`);
+        }
+        if (!Number.isInteger(col) || col < 1) {
+            throw new RangeError(`cell column ${col} is out of bounds — columns start at 1`);
+        }
+        this.row = row;
+        this.col = col;
+    }
+    /** Canonical A1 address of this cell (`"B3"`). */
+    get address() {
+        return encodeAddress(this.col, this.row);
+    }
+    /** The cell's value; `null` when empty. Assigning `undefined` clears it. */
+    get value() {
+        return this.#value;
+    }
+    set value(value) {
+        this.#value = coerceCellValue(value);
+    }
+    /** The observable {@link ValueType} of the current value. */
+    get type() {
+        return detectValueType(this.#value);
+    }
+    /**
+     * Assign rich text whose runs **inherit this cell's font**, so a run needs to state only what it
+     * changes: `setRichText([{text: 'Note:', font: {bold: true}}, {text: ' the rest'}])` keeps the
+     * cell's typeface, size and colour throughout and bolds the first run.
+     *
+     * This exists because a run's format element does **not** inherit anything. A `<rPr>` is a
+     * *complete* character format, and any facet it omits falls back to the workbook default font
+     * ({@link Workbook.defaultFont}) — not to the cell's. Verified against Excel: a cell set to
+     * Courier New 16 whose first run carries only `<b/>` renders that run in the workbook default face
+     * at the default size, bold, while the rest of the cell renders Courier New 16. So a run authored
+     * as `{bold: true}` beside a styled cell silently loses the face, which is the format's rule rather
+     * than a bug — and the reason this is a helper rather than a change to how runs are written.
+     *
+     * Composition is per facet: a facet the run names wins, one it omits comes from the cell. Assigning
+     * `value` directly stays the bare path, for a caller who wants a run that deliberately falls back
+     * to the workbook default.
+     *
+     * A cell that names no font of its own needs no composition — an omitted facet already falls back
+     * to the workbook default, which is exactly what such a cell renders in — so the runs pass through
+     * unchanged.
+     */
+    setRichText(runs) {
+        const base = this.#font;
+        this.#value =
+            base === undefined
+                ? { richText: [...runs] }
+                : { richText: runs.map((run) => ({ ...run, font: { ...base, ...run.font } })) };
+    }
+    /**
+     * The cell's full style — fill, number format, font, border, alignment, and protection — as one
+     * {@link CellStyle}, for restyling a cell wholesale without importing {@link applyCellStyle}
+     * separately (mirrors {@link Worksheet.model}'s getter/setter pair for the whole sheet). The
+     * getter carries only the facets this cell has set (the same shape {@link cellToModel} emits);
+     * the setter lays each facet `style` carries onto this cell — like every per-facet setter, it
+     * replaces that facet outright but leaves a facet `style` omits untouched, so `cell.style = {...}`
+     * composes with prior per-facet sets rather than clearing them wholesale.
+     */
+    get style() {
+        const style = {};
+        assignStyleFacets(style, this);
+        return style;
+    }
+    set style(style) {
+        applyCellStyle(this, style);
+    }
+    /** The cell's background fill, or `undefined` when it has none. */
+    get fill() {
+        return this.#fill;
+    }
+    set fill(fill) {
+        this.#fill = fill;
+    }
+    /**
+     * The cell's number-format code (`"0.00%"`, a custom accounting format, …), or
+     * `undefined` for the General format. Stored verbatim: the invariant form Excel
+     * persists — `.` decimal, `,` grouping, `/` date separator — is neither localized
+     * nor rewritten, so the code round-trips character-for-character. A cell that also carries
+     * a column-level format keeps both, so overriding one facet never drops the other.
+     */
+    get numFmt() {
+        return this.#numFmt;
+    }
+    set numFmt(numFmt) {
+        this.#numFmt = numFmt;
+    }
+    /**
+     * The cell's font — bold/italic/underline, size, colour, typeface — as a partial set
+     * of the facets that differ from the default (only the facets actually set are carried,
+     * exactly as OOXML stores them). `undefined` means the cell uses the workbook default font.
+     */
+    get font() {
+        return this.#font;
+    }
+    set font(font) {
+        this.#font = font;
+    }
+    /**
+     * The cell's border — the line style and colour of each side — or `undefined` when the
+     * cell has none. An absent edge within a border means that side is unbordered, so reading
+     * a cell never fabricates a border it does not have.
+     */
+    get border() {
+        return this.#border;
+    }
+    set border(border) {
+        this.#border = border;
+    }
+    /**
+     * The cell's alignment — how its content sits within the cell, plus the wrap/shrink flags —
+     * or `undefined` when it uses the defaults. The boolean flags are off unless explicitly set,
+     * so a cell that never enabled wrapping never reads back wrapped.
+     */
+    get alignment() {
+        return this.#alignment;
+    }
+    set alignment(alignment) {
+        this.#alignment = alignment;
+    }
+    /**
+     * The cell's protection — its locked/hidden flags, enforced only once the sheet is protected —
+     * or `undefined` when the cell carries neither. `locked` defaults to on in OOXML, so a cell
+     * that never touched protection is implicitly locked and reads back as `undefined`, not as
+     * `{locked: true}`; the flag only becomes explicit when a cell is unlocked.
+     */
+    get protection() {
+        return this.#protection;
+    }
+    set protection(protection) {
+        this.#protection = protection;
+    }
+    /**
+     * The quote-prefix flag: when set, a spreadsheet stores the cell's content as literal text even
+     * when it looks like a formula or number, and shows a leading apostrophe in the formula bar without
+     * that apostrophe being part of the stored value. `undefined` (or `false`) when unset. It is a
+     * cell-format flag — an attribute on the cell's `xf` record — so it composes independently of the
+     * value.
+     */
+    get quotePrefix() {
+        return this.#quotePrefix;
+    }
+    set quotePrefix(quotePrefix) {
+        this.#quotePrefix = quotePrefix;
+    }
+    /**
+     * The index of the named cell style this cell links to (its OOXML `xfId`), or `undefined` when the
+     * cell references no named style beyond the default. The cell inherits any facet its own direct
+     * format leaves unset from that named style; the reader resolves the effective look onto the cell's
+     * own facets, and this link is preserved so a round-trip keeps the cell tied to its named style
+     * rather than flattening it away.
+     *
+     * Codec-only: an index is meaningful only against the workbook's `namedStyles` table as the reader
+     * built it, and a value naming no entry leaves the cell pointing at nothing. Authors set the facets
+     * they want directly.
+     */
+    get [NAMED_STYLE_ID]() {
+        return this.#namedStyleId;
+    }
+    set [NAMED_STYLE_ID](namedStyleId) {
+        this.#namedStyleId = namedStyleId;
+    }
+    /**
+     * The cell's note (comment) as plain text, or `undefined` when it carries none. A note is
+     * metadata anchored to the cell, independent of its value: a cell can hold a note while empty,
+     * and clearing the value leaves the note intact. A structural edit that shifts the cell carries the
+     * note along to its new position.
+     */
+    get note() {
+        return this.#note;
+    }
+    set note(note) {
+        this.#note = note;
+    }
+}
+// Lay each present style facet of `style` onto `cell`, leaving facets it omits untouched. A {@link Cell}
+// exposes every facet as a setter of its declared type, so it *is* a mutable {@link CellStyle} target and
+// the shared {@link assignStyleFacets} loop drives it — the facet list lives only on {@link CellStyle}, and
+// no apply path can forget a facet without a compile error there. Facet objects are assigned by reference,
+// safe under the copy-on-write style model (setters replace, never mutate in place). This is the named
+// entry point for the many paths that style a cell — a table column's format, a resolved read xf, a model
+// assignment — so their call sites read as intent, not as a raw record copy.
+export function applyCellStyle(cell, style) {
+    assignStyleFacets(cell, style);
+}
+// Copy a cell's value and every style facet onto a target cell. The source is a {@link CellModel},
+// which a live {@link Cell} structurally satisfies, so this one primitive serves both directions that
+// load content into a cell: a structural edit shifting a cell to fresh coordinates (`Cell` fixes its
+// `(row, col)` at construction, so the shifted cell is a new cell carrying the original's content) and
+// assigning a {@link WorksheetModel} onto a sheet. Position is never copied — the target keeps its own
+// `(row, col)`. The style facets go through {@link applyCellStyle} (targets are always fresh cells, so
+// its skip-if-absent is equivalent to a full copy here). Paired with {@link cellToModel} (the read
+// direction); a facet cellToModel emits but applyCellStyle omits (or the reverse) would silently drop
+// on a model round-trip — the historical merge-loss failure the CellStyle tuple now guards by type.
+export function copyCellContent(source, target) {
+    target.value = source.value;
+    applyCellStyle(target, source);
+    target.note = source.note;
+}
+// Snapshot a cell's position and content as a {@link CellModel} — the read direction paired with
+// {@link copyCellContent}'s write. The style facets flow through the same {@link assignStyleFacets} loop
+// as every other copy (a {@link Cell} is structurally a {@link CellStyle} source), so this direction emits
+// exactly the facets the apply direction consumes: a `dst.model = src.model` round-trip carries every one,
+// and a facet added to {@link CellStyle} propagates here without a hand edit. Facets the cell does not
+// carry are left off the model rather than pinned to `undefined`; no consumer distinguishes the two.
+export function cellToModel(cell) {
+    const model = {
+        row: cell.row,
+        col: cell.col,
+        value: cell.value,
+        note: cell.note,
+    };
+    assignStyleFacets(model, cell);
+    return model;
+}

package/dist/core/color-resolution.d.ts

@@ -0,0 +1,58 @@
+import type { Color } from './style.ts';
+import { type ThemeColorScheme } from './theme.ts';
+/**
+ * The built-in indexed colour palette (ECMA-376 §18.8.27), by index. Entries 0–7 duplicate 8–15 —
+ * redundancy the spec preserves for backwards compatibility with the legacy formats this palette came
+ * from — and the table is only 64 long: indices 64 and 65 are the *system* foreground and background,
+ * which name whatever the operating system's window colours are and therefore have no fixed value at
+ * all (see {@link SYSTEM_INDEXED_COLORS}).
+ *
+ * The spec writes each entry with a leading `00`. That byte is not an alpha channel — a palette of
+ * fully transparent colours would be absurd — it is an artefact of the 32-bit colour records these
+ * values were lifted from, which is why {@link resolveColor} returns them fully opaque.
+ */
+export declare const DEFAULT_INDEXED_COLORS: readonly string[];
+/**
+ * The two indices that are not colours: 64 is the system foreground and 65 the system background.
+ * They resolve to whatever the viewing system's window colours are, so this library reports them
+ * unresolved rather than inventing black and white — a caller that wants to paint them must decide
+ * for itself what "automatic" means in its context. `indexed="64"` in particular is extremely common:
+ * it is the placeholder every solid fill Excel writes carries as its background colour.
+ */
+export declare const SYSTEM_INDEXED_COLORS: ReadonlySet<number>;
+/** What a colour reference is resolved against: the workbook's theme scheme and indexed palette. */
+export interface ColorResolutionContext {
+    /** The theme's colour scheme; the Office default when the workbook carries no theme of its own. */
+    readonly theme?: ThemeColorScheme | undefined;
+    /**
+     * The workbook's custom indexed palette, by index, each entry an ARGB string. Empty or absent means
+     * the workbook rides {@link DEFAULT_INDEXED_COLORS}. A custom palette replaces the built-in one
+     * wholesale — that is what `<indexedColors>` means — so a short custom palette leaves the indices
+     * past its end unresolved rather than falling through to the built-in entry.
+     */
+    readonly indexed?: readonly string[] | undefined;
+}
+/**
+ * Resolve a colour reference to a concrete 8-hex ARGB string, or `undefined` when it cannot be
+ * resolved — an `auto` colour, a system indexed colour, a theme slot the workbook's scheme does not
+ * declare, or an index past the end of a custom palette.
+ *
+ * Precedence follows what the encodings mean: an explicit `argb` is already concrete and wins; then
+ * `theme`, then `indexed`. A `tint` applies to whatever the base resolved to.
+ *
+ * Alpha: a resolved `theme`/`indexed` colour comes back fully opaque, because neither the theme scheme
+ * nor the palette carries a meaningful alpha (see {@link DEFAULT_INDEXED_COLORS}). An explicit `argb`
+ * keeps the alpha the file stated.
+ */
+export declare function resolveColor(color: Color, context?: ColorResolutionContext): string | undefined;
+/**
+ * Apply a `tint` to a concrete ARGB colour: convert to HLS, shift the luminance, convert back.
+ *
+ * The shift is ECMA-376's (§18.3.1.15): `-1` darkens to black, `+1` lightens to white, `0` is a
+ * no-op. The spec states the formula but not the rounding either side of the RGB↔HLS conversion, so
+ * an implementation cannot be checked against the prose alone. This one lands within 2/255 per
+ * channel of what Excel Desktop itself renders, measured over three hues × twelve tints and recorded
+ * in `test/corpus/fixtures/excel-oracle/theme-color-tint-luminance.json`. Closing that last gap would
+ * mean reproducing one Excel build's fixed-point HLS rounding, and the difference is not visible.
+ */
+export declare function applyTint(argb: string, tint: number): string;

package/dist/core/color-resolution.js

@@ -0,0 +1,170 @@
+// Turning an OOXML colour *reference* into a concrete colour.
+//
+// A `<color>` in a spreadsheet states its value in one of three ways, and two of them are references
+// that mean nothing on their own: `indexed="n"` points into a 64-entry legacy palette carried over
+// from the BIFF era, and `theme="n"` points into the workbook theme's colour scheme. Either may
+// additionally carry a `tint`, which lightens or darkens whatever it resolved to.
+//
+// Resolution is deliberately a *derived* view. Nothing here writes back into the model: a `Color`
+// keeps the encoding its file used, so a round-trip re-emits `theme="4" tint="0.4"` rather than
+// rewriting every cell as a literal ARGB — which would bloat the styles table, break the link to the
+// theme (recolouring the workbook would stop working), and change what the file means.
+import { DEFAULT_THEME_COLOR_SCHEME, THEME_COLOR_SLOTS } from "./theme.js";
+/**
+ * The built-in indexed colour palette (ECMA-376 §18.8.27), by index. Entries 0–7 duplicate 8–15 —
+ * redundancy the spec preserves for backwards compatibility with the legacy formats this palette came
+ * from — and the table is only 64 long: indices 64 and 65 are the *system* foreground and background,
+ * which name whatever the operating system's window colours are and therefore have no fixed value at
+ * all (see {@link SYSTEM_INDEXED_COLORS}).
+ *
+ * The spec writes each entry with a leading `00`. That byte is not an alpha channel — a palette of
+ * fully transparent colours would be absurd — it is an artefact of the 32-bit colour records these
+ * values were lifted from, which is why {@link resolveColor} returns them fully opaque.
+ */
+// biome-ignore format: laid out eight per row, matching how the spec tabulates the palette —
+// the 0-7 / 8-15 duplication and the 16-entry banding are legible here and invisible one-per-line.
+export const DEFAULT_INDEXED_COLORS = [
+    '00000000', '00FFFFFF', '00FF0000', '0000FF00', '000000FF', '00FFFF00', '00FF00FF', '0000FFFF',
+    '00000000', '00FFFFFF', '00FF0000', '0000FF00', '000000FF', '00FFFF00', '00FF00FF', '0000FFFF',
+    '00800000', '00008000', '00000080', '00808000', '00800080', '00008080', '00C0C0C0', '00808080',
+    '009999FF', '00993366', '00FFFFCC', '00CCFFFF', '00660066', '00FF8080', '000066CC', '00CCCCFF',
+    '00000080', '00FF00FF', '00FFFF00', '0000FFFF', '00800080', '00800000', '00008080', '000000FF',
+    '0000CCFF', '00CCFFFF', '00CCFFCC', '00FFFF99', '0099CCFF', '00FF99CC', '00CC99FF', '00FFCC99',
+    '003366FF', '0033CCCC', '0099CC00', '00FFCC00', '00FF9900', '00FF6600', '00666699', '00969696',
+    '00003366', '00339966', '00003300', '00333300', '00993300', '00993366', '00333399', '00333333',
+];
+/**
+ * The two indices that are not colours: 64 is the system foreground and 65 the system background.
+ * They resolve to whatever the viewing system's window colours are, so this library reports them
+ * unresolved rather than inventing black and white — a caller that wants to paint them must decide
+ * for itself what "automatic" means in its context. `indexed="64"` in particular is extremely common:
+ * it is the placeholder every solid fill Excel writes carries as its background colour.
+ */
+export const SYSTEM_INDEXED_COLORS = new Set([64, 65]);
+/**
+ * Resolve a colour reference to a concrete 8-hex ARGB string, or `undefined` when it cannot be
+ * resolved — an `auto` colour, a system indexed colour, a theme slot the workbook's scheme does not
+ * declare, or an index past the end of a custom palette.
+ *
+ * Precedence follows what the encodings mean: an explicit `argb` is already concrete and wins; then
+ * `theme`, then `indexed`. A `tint` applies to whatever the base resolved to.
+ *
+ * Alpha: a resolved `theme`/`indexed` colour comes back fully opaque, because neither the theme scheme
+ * nor the palette carries a meaningful alpha (see {@link DEFAULT_INDEXED_COLORS}). An explicit `argb`
+ * keeps the alpha the file stated.
+ */
+export function resolveColor(color, context = {}) {
+    const base = resolveBase(color, context);
+    if (base === undefined)
+        return undefined;
+    const { tint } = color;
+    if (tint === undefined || !Number.isFinite(tint) || tint === 0)
+        return base;
+    return applyTint(base, tint);
+}
+function resolveBase(color, context) {
+    if (color.argb !== undefined)
+        return normalizeArgb(color.argb);
+    if (color.theme !== undefined) {
+        const slot = THEME_COLOR_SLOTS[color.theme];
+        if (slot === undefined)
+            return undefined;
+        const value = (context.theme ?? DEFAULT_THEME_COLOR_SCHEME)[slot];
+        return value === undefined ? undefined : `FF${value.toUpperCase()}`;
+    }
+    if (color.indexed !== undefined) {
+        if (SYSTEM_INDEXED_COLORS.has(color.indexed))
+            return undefined;
+        const custom = context.indexed;
+        const entry = custom !== undefined && custom.length > 0
+            ? custom[color.indexed]
+            : DEFAULT_INDEXED_COLORS[color.indexed];
+        if (entry === undefined)
+            return undefined;
+        const normalized = normalizeArgb(entry);
+        return normalized === undefined ? undefined : `FF${normalized.slice(2)}`;
+    }
+    return undefined;
+}
+// Accept the shapes a colour value legitimately arrives in — 6-hex RGB, 8-hex ARGB, either with a
+// leading '#' — and reject anything else rather than returning a half-parsed value. This is a *read*
+// path over foreign data, so a malformed entry resolves to nothing; the writer's own normaliser
+// throws, because there the malformed value is a caller's bug.
+function normalizeArgb(value) {
+    const hex = value.startsWith('#') ? value.slice(1) : value;
+    const argb = hex.length === 6 ? `FF${hex}` : hex;
+    return /^[0-9a-fA-F]{8}$/.test(argb) ? argb.toUpperCase() : undefined;
+}
+/**
+ * Apply a `tint` to a concrete ARGB colour: convert to HLS, shift the luminance, convert back.
+ *
+ * The shift is ECMA-376's (§18.3.1.15): `-1` darkens to black, `+1` lightens to white, `0` is a
+ * no-op. The spec states the formula but not the rounding either side of the RGB↔HLS conversion, so
+ * an implementation cannot be checked against the prose alone. This one lands within 2/255 per
+ * channel of what Excel Desktop itself renders, measured over three hues × twelve tints and recorded
+ * in `test/corpus/fixtures/excel-oracle/theme-color-tint-luminance.json`. Closing that last gap would
+ * mean reproducing one Excel build's fixed-point HLS rounding, and the difference is not visible.
+ */
+export function applyTint(argb, tint) {
+    const alpha = argb.slice(0, 2);
+    const r = Number.parseInt(argb.slice(2, 4), 16) / 255;
+    const g = Number.parseInt(argb.slice(4, 6), 16) / 255;
+    const b = Number.parseInt(argb.slice(6, 8), 16) / 255;
+    const max = Math.max(r, g, b);
+    const min = Math.min(r, g, b);
+    const lightness = (max + min) / 2;
+    let saturation = 0;
+    let hue = 0;
+    if (max !== min) {
+        const delta = max - min;
+        saturation = lightness > 0.5 ? delta / (2 - max - min) : delta / (max + min);
+        if (max === r)
+            hue = (g - b) / delta + (g < b ? 6 : 0);
+        else if (max === g)
+            hue = (b - r) / delta + 2;
+        else
+            hue = (r - g) / delta + 4;
+        hue /= 6;
+    }
+    // Lum' = Lum * (1 + tint) when darkening; Lum' = Lum * (1 - tint) + tint when lightening. The
+    // spec writes the second as `Lum * (1 - tint) + (HLSMAX - HLSMAX * (1 - tint))`, which is the same
+    // thing once the HLSMAX scale is divided out.
+    const shifted = tint < 0 ? lightness * (1 + tint) : lightness * (1 - tint) + tint;
+    return alpha + hlsToRgbHex(hue, saturation, clamp01(shifted));
+}
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+function hlsToRgbHex(hue, saturation, lightness) {
+    if (saturation === 0) {
+        const grey = channelHex(lightness);
+        return grey + grey + grey;
+    }
+    const q = lightness < 0.5
+        ? lightness * (1 + saturation)
+        : lightness + saturation - lightness * saturation;
+    const p = 2 * lightness - q;
+    return (channelHex(hueToChannel(p, q, hue + 1 / 3)) +
+        channelHex(hueToChannel(p, q, hue)) +
+        channelHex(hueToChannel(p, q, hue - 1 / 3)));
+}
+function hueToChannel(p, q, offset) {
+    let t = offset;
+    if (t < 0)
+        t += 1;
+    if (t > 1)
+        t -= 1;
+    if (t < 1 / 6)
+        return p + (q - p) * 6 * t;
+    if (t < 1 / 2)
+        return q;
+    if (t < 2 / 3)
+        return p + (q - p) * (2 / 3 - t) * 6;
+    return p;
+}
+function channelHex(value) {
+    return Math.round(clamp01(value) * 255)
+        .toString(16)
+        .toUpperCase()
+        .padStart(2, '0');
+}

package/dist/core/column.d.ts

@@ -0,0 +1,87 @@
+import type { Cell } from './cell.ts';
+import type { Alignment, Border, Fill, Font, Protection } from './style.ts';
+import type { CellValue } from './value.ts';
+import type { ColumnProperties, Worksheet } from './worksheet.ts';
+export declare class Column {
+    #private;
+    /** 1-based column index. Fixed for this handle's lifetime. */
+    readonly index: number;
+    /** @throws {RangeError} if the index is not a positive integer. */
+    constructor(sheet: Worksheet, index: number);
+    /** The column's letters (`"B"`) — the spreadsheet-facing name for {@link index}. */
+    get letter(): string;
+    /**
+     * The column's format record if it has one, else `undefined` — a read that never fabricates, so a
+     * serializer can ask every column it visits whether there are attributes to emit without giving
+     * each one an empty record. Read-only on purpose: {@link width} and its siblings are how a column
+     * is formatted, and they create the record on first write.
+     */
+    get properties(): Readonly<ColumnProperties> | undefined;
+    /**
+     * Stable key naming this column so a keyed-object row (see {@link Worksheet.addRow}) can place a
+     * value under it by name rather than position. In-memory only — never serialized to OOXML.
+     */
+    get key(): string | undefined;
+    set key(key: string | undefined);
+    /** Column width in character units; `undefined` leaves the sheet default in force. */
+    get width(): number | undefined;
+    set width(width: number | undefined);
+    /** Whether the column is hidden. */
+    get hidden(): boolean | undefined;
+    set hidden(hidden: boolean | undefined);
+    /** Outline (grouping) depth; 0 or `undefined` means ungrouped. */
+    get outlineLevel(): number | undefined;
+    set outlineLevel(outlineLevel: number | undefined);
+    /** Whether this column is the collapsed summary of an outline group. */
+    get collapsed(): boolean | undefined;
+    set collapsed(collapsed: boolean | undefined);
+    /** Default fill for the column's cells that set none of their own. */
+    get fill(): Fill | undefined;
+    set fill(fill: Fill | undefined);
+    /** Default number format for the column's cells that set none of their own. */
+    get numFmt(): string | undefined;
+    set numFmt(numFmt: string | undefined);
+    /** Default font for the column's cells that set none of their own. */
+    get font(): Font | undefined;
+    set font(font: Font | undefined);
+    /** Default border for the column's cells that set none of their own. */
+    get border(): Border | undefined;
+    set border(border: Border | undefined);
+    /** Default alignment for the column's cells that set none of their own. */
+    get alignment(): Alignment | undefined;
+    set alignment(alignment: Alignment | undefined);
+    /** Default protection flags for the column's cells that set none of their own. */
+    get protection(): Protection | undefined;
+    set protection(protection: Protection | undefined);
+    /**
+     * The cell at a 1-based row number in this column, creating it on first access. Resolves through
+     * merges exactly as {@link Worksheet.getCell} does.
+     *
+     * @throws {RangeError} if the row is not a positive integer.
+     */
+    getCell(row: number): Cell;
+    /**
+     * The column's materialised cells in ascending row order. Sparse: a row that never wrote to this
+     * column has no cell here.
+     */
+    get cells(): readonly Cell[];
+    /**
+     * The column's values by position, index 0 being row 1. Sparse in the same way {@link cells} is:
+     * a row with no cell in this column is a hole, which is what distinguishes "never written" from a
+     * cell holding `null`.
+     *
+     * Assigning places each value it names and leaves every other row untouched, mirroring
+     * {@link Row.values} — a hole or an explicit `undefined` skips that row, and a shorter array does
+     * not clear the tail.
+     */
+    get values(): (CellValue | undefined)[];
+    set values(values: (CellValue | undefined)[]);
+}
+type AssertNever<T extends never> = T;
+/**
+ * Compile-time proof that {@link Column} mirrors every {@link ColumnProperties} field — including
+ * the six inherited `CellStyle` facets, so a seventh facet reaches this handle the moment it joins
+ * the tuple. See the counterpart on `Row` for why the mirror needs proving rather than reviewing.
+ */
+export type EveryColumnPropertyIsMirrored = AssertNever<Exclude<keyof ColumnProperties, keyof Column & keyof ColumnProperties>>;
+export {};