Styles

Set the horizontal alignment in isolation.

function alignCellHorizontal(wb: Workbook, c: Cell, horizontal: HorizontalAlignment): void

Set the vertical alignment in isolation.

function alignCellVertical(wb: Workbook, c: Cell, vertical: VerticalAlignment): void

Apply a built-in Excel style ("Heading 1" / "Total" / "Good" / "Bad" / "Calculation" / etc.) to a single cell. Registers the built-in on the Stylesheet (idempotent) and points the cell's xf at it via `xfId` while inheriting the matching font/fill/border/ numFmt ids so the cell renders correctly on its own. Throws when `name` isn't in BUILTIN_NAMED_STYLES; use applyNamedStyle for user-registered styles.

function applyBuiltinStyle(wb: Workbook, c: Cell, name: string): void

Apply a NamedStyle that's already registered on the workbook (via `addNamedStyle` or `ensureBuiltinStyle`) to a single cell, by name.

function applyNamedStyle(wb: Workbook, c: Cell, name: string): void

Aggregate `fontToCss` + `fillToCss` + `borderToCss` + `alignmentToCss` for a cell into a single CSS-property record. Resolves the cell's `styleId` against the workbook stylesheet, then merges the four partials. On key collision the priority is alignment > border > fill > font (alignment is most specific, font is the broad default). A fully-default cell (`styleId === 0` with empty pools) returns `{}`.

function cellStyleToCss(wb: Workbook, c: Cell): Record<string, string>

Center a cell horizontally + vertically. Mirrors Excel's "Merge & Center" UI button (without the merge — see mergeCells for that). Preserves any other alignment fields already present.

function centerCell(wb: Workbook, c: Cell): void

Strip the cell's background fill, returning it to the default.

function clearCellBackground(wb: Workbook, c: Cell): void

Reset a cell back to the default (unstyled) appearance — equivalent to Excel's "Clear Formatting" command. After the call, the cell inherits the workbook's default font / fill / border / alignment / protection / numberFormat. The underlying xf pool is **not** shrunk (Excel doesn't bother either; the orphaned xf is harmless).

function clearCellStyle(_wb: Workbook, c: Cell): void

Range-level shortcut for clearCellStyle. Walks every cell actually present in the range and resets its `styleId` to 0; cells that don't exist yet are **not** materialised (no-op for sparse regions, unlike the styled `setRange*` family which has to create cells to make the patch observable).

function clearRangeStyle(wb: Workbook, ws: Worksheet, range: string): void

Deep-copy the source cell's full xf (font / fill / border / alignment / protection / numberFormat) into a possibly-different workbook. Returns the new styleId in the target workbook.

function cloneCellStyle(sourceWb: Workbook, source: Cell, targetWb: Workbook, target: Cell): number

Copy the source cell's `styleId` to the target cell. Both cells share the same workbook stylesheet, so the styled appearance carries over without allocating a new xf entry. Pass cells from different workbooks via cloneCellStyle if you need a deep copy across workbooks.

function copyCellStyle(_wb: Workbook, source: Cell, target: Cell): void

Apply Excel's stock "table header" formatting to a range: bold white text on a dark fill, plus a thick bottom border. Override any axis via `opts` — pass `bold: false` to drop the bold, or `fillColor: 'FF305496'` for a different shade. Defaults match Excel's "Table Style Medium 2" header row.

function formatAsHeader(wb: Workbook, ws: Worksheet, range: string, opts?: { bold?: boolean; bottomBorder?: false | SideStyle; bottomBorderColor?: string | Partial<Color>; fillColor?: string | Partial<Color>; fontColor?: string | Partial<Color> }): void

Returns the cell's number-format **code** (e.g. `"0.00"`, `"General"`). Built-in IDs resolve through `builtinFormatCode`; custom IDs come from the workbook's numFmts map.

function getCellNumberFormat(wb: Workbook, c: Cell): string

Set or clear the indent level (0..255).

function indentCell(wb: Workbook, c: Cell, levels: number): void

Rotate the cell's text. `degrees` accepts 0..180 (clockwise) or 255 for Excel's "vertical stacked" mode. Mirrors the rotate icons in the alignment ribbon.

function rotateCellText(wb: Workbook, c: Cell, degrees: number): void

Toggle bold on a cell. Preserves other font fields.

function setBold(wb: Workbook, c: Cell, on?: boolean): void

Format a cell as currency. Produces one of: - default → `"$#,##0.00"` (US dollar, 2 decimals) - `{ symbol: "€" }` → `"€#,##0.00"` - `{ symbol: "¥", decimals: 0 }` → `"¥#,##0"` - `{ accounting: true }` → `"_-$* #,##0.00_-;-$* #,##0.00_-;_-$* \"-\"??_-;_-@_-"` (Excel's "Accounting" subtype with right-aligned symbol).

function setCellAsCurrency(wb: Workbook, c: Cell, opts?: { accounting?: boolean; decimals?: number; symbol?: string }): void

Format a cell as a date. `format` defaults to Excel's default locale-independent ISO-style date `"yyyy-mm-dd"`. Common alternatives: `"m/d/yyyy"`, `"dd-mmm-yy"`, `"yyyy-mm-dd hh:mm:ss"`.

function setCellAsDate(wb: Workbook, c: Cell, format?: string): void

Format a cell as a thousands-separated number. `decimals` defaults to 0 → `"#,##0"`; `decimals: 2` → `"#,##0.00"`.

function setCellAsNumber(wb: Workbook, c: Cell, decimals?: number): void

Format a cell as a percentage. `decimals` defaults to 0 → `"0%"`; `decimals: 2` → `"0.00%"`. The cell value is multiplied by 100 by Excel during display.

function setCellAsPercent(wb: Workbook, c: Cell, decimals?: number): void

Set the cell's background to a solid color. Accepts a hex string (`'FFAAFFAA'`) or a partial `Color` object (`{ theme: 4, tint: 0.4 }`). Equivalent to `setCellFill(wb, c, makePatternFill({ patternType: 'solid', fgColor: makeColor(...) }))`.

function setCellBackgroundColor(wb: Workbook, c: Cell, color: string | Partial<Color>): void

Apply the same SideStyle to all four edges of a single cell. Optional color via hex string or `Color` partial. Equivalent to `setCellBorder(wb, c, makeBorder({ left, right, top, bottom: side }))` with all four sides identical.

function setCellBorderAll(wb: Workbook, c: Cell, opts?: { color?: string | Partial<Color>; style: SideStyle }): void

Set the cell's number format by its **code** string. Built-in codes resolve to their canonical id; custom codes are registered via `addNumFmt`.

function setCellNumberFormat(wb: Workbook, c: Cell, formatCode: string): void

Combined cell-style setter. Each axis is independent — pass any subset and the corresponding `applyXxx` flags get set on the underlying CellXf. Avoids 5+ separate stylesheet round-trips when a caller wants to style a single cell across multiple axes (Excel dedupes the resulting xf record on every call).

function setCellStyle(wb: Workbook, c: Cell, opts: { alignment?: Alignment; border?: Border; fill?: Fill; font?: Font; numberFormat?: string; protection?: Protection }): void

Set the font color. Accepts a hex string ("FFAA0033") or a partial `Color` object (`{ theme: 4, tint: 0.4 }`). Preserves other font fields.

function setFontColor(wb: Workbook, c: Cell, color: string | Partial<Color>): void

Set the font family name (e.g. "Arial"). Preserves other fields.

function setFontName(wb: Workbook, c: Cell, name: string): void

Set the font size in points (e.g. 14). Preserves other fields.

function setFontSize(wb: Workbook, c: Cell, size: number): void

Toggle italic on a cell.

function setItalic(wb: Workbook, c: Cell, on?: boolean): void

Range-level Alignment setter. Two modes: - `mode: 'merge'` (default) — each cell's existing alignment is preserved; the supplied partial overlays it. Use this when you want to set just `horizontal` or `vertical` without wiping the other axes. - `mode: 'replace'` — each cell's alignment is **wholly replaced** by the supplied value. Indent / textRotation / wrapText that weren't supplied are dropped. Empty cells in the range are materialised so the patch is observable on round-trip.

function setRangeAlignment(wb: Workbook, ws: Worksheet, range: string, alignment: Partial<Alignment>, mode?: "replace" | "merge"): void

Range-level shortcut for `setCellBackgroundColor`. Each cell in the range gets the same solid pattern fill via `setRangeStyle`, so the fill pool dedups to a single entry across the whole range.

function setRangeBackgroundColor(wb: Workbook, ws: Worksheet, range: string, color: string | Partial<Color>): void

Draw an outer border around a rectangular range. Cells on the perimeter receive a partial border (only the edges that face outside the range); inner cells are unaffected unless `inner` is provided, in which case every cell in the range receives a border combining its perimeter edges with the `inner` style for the inside edges.

function setRangeBorderBox(wb: Workbook, ws: Worksheet, range: string, opts?: { color?: string | Partial<Color>; inner?: SideStyle; style: SideStyle }): void

Range-level shortcut for `setCellFont` (full Font replacement).

function setRangeFont(wb: Workbook, ws: Worksheet, range: string, font: Font): void

Range-level shortcut for `setCellNumberFormat`. Stamps the same format-code onto every cell in the range; the numFmt pool dedups the code so callers don't pay per-cell pool churn.

function setRangeNumberFormat(wb: Workbook, ws: Worksheet, range: string, formatCode: string): void

Range-level shortcut for `setCellProtection`. Stamps the same Protection (locked / hidden) onto every cell in the range. Pass a full `Protection` value or a partial — partials default missing fields to `false` per Excel's `<protection>` semantics. Common usage: `setRangeProtection(wb, ws, 'B2:B100', { locked: false })` to leave just an input column editable when the sheet is protected.

function setRangeProtection(wb: Workbook, ws: Worksheet, range: string, protection: Protection | Partial<Protection>): void

Build a single CellXf id from a multi-axis style spec, then apply it to every cell in `range`. The xf is registered once per style shape, so a 1000-cell range allocates one xf — much faster than looping `setCellStyle` per cell.

function setRangeStyle(wb: Workbook, ws: Worksheet, range: string, opts: { alignment?: Alignment; border?: Border; fill?: Fill; font?: Font; numberFormat?: string; protection?: Protection }): void

Range-level shortcut for `wrapCellText`. Toggles "Wrap Text" on every cell in the range while preserving each cell's existing alignment (horizontal / vertical / textRotation / indent are not touched). Empty cells in the range are materialised so the alignment patch is observable on round-trip.

function setRangeWrapText(wb: Workbook, ws: Worksheet, range: string, on?: boolean): void

Toggle strike-through on a cell.

function setStrikethrough(wb: Workbook, c: Cell, on?: boolean): void

Set the underline style. Pass `false` to drop underline; pass `'single' | 'double' | 'singleAccounting' | 'doubleAccounting'` to apply that style; pass `true` for the most common single-line.

function setUnderline(wb: Workbook, c: Cell, style?: boolean | UnderlineStyle): void

Toggle "Wrap Text" on a cell, preserving other alignment fields.

function wrapCellText(wb: Workbook, c: Cell, wrap?: boolean): void

Look up the format code for a given numFmtId, or `undefined` if unknown.

function builtinFormatCode(id: number): string | undefined

Look up the numFmtId for a given format code, or `undefined` if not built-in.

function builtinFormatId(code: string): number | undefined

Categorise a date format as 'date', 'time', 'datetime' or undefined.

function classifyDateFormat(code: string | null | undefined): "date" | "time" | "datetime" | undefined

True iff `code` is one of the OOXML built-in format strings.

function isBuiltinFormat(code: string): boolean

Heuristic: does the format string imply a date / time interpretation? Looks at only the first format section (positive-value branch); strips literals, colour codes and locale modifiers before scanning for date tokens (d/m/h/y/s, case-insensitive) that aren't escaped.

function isDateFormat(code: string | null | undefined): boolean

Heuristic: does the format string indicate a duration ([h]:mm:ss etc.)?

function isTimedeltaFormat(code: string | null | undefined): boolean

Canonical OOXML built-in number formats — verbatim from openpyxl.

const BUILTIN_FORMATS: Readonly<Record<number, string>>

First numFmtId Excel reserves for user-defined formats.

const BUILTIN_FORMATS_MAX_SIZE: 164

Adjust the lightness of a color by `delta` (added directly to the `[0, 1]` lightness channel and clamped). Positive = lighter, negative = darker. Distinct from lighten / darken which mix toward white/black in RGB space.

function adjustLightness(hex: string, delta: number): string

Adjust the saturation of a color by `delta` (added directly to the `[0, 1]` saturation channel and clamped). Positive = more vivid, negative = closer to gray. Hue, lightness, and alpha are preserved.

function adjustSaturation(hex: string, delta: number): string

Read a Color value-object back to a normalised ARGB hex. Resolution order: explicit `rgb` → `indexed` palette lookup. Returns `undefined` for `theme` / `auto` / empty inputs (unresolvable without a theme), so callers can fall back to a default.

function colorToHex(color: Color | undefined): string | undefined

WCAG contrast ratio between two ARGB hex colors. Returns a value in `[1, 21]`; 1 = identical luminance, 21 = pure black on pure white. The order of arguments doesn't matter.

function contrastRatio(hexA: string, hexB: string): number

Darken a color by mixing it with black. `amount` is in `[0, 1]`: 0 returns the input unchanged, 1 returns pure black (preserving the alpha channel).

function darken(hex: string, amount: number): string

Convert an ARGB / RGB hex to its HSL representation. Returns `{ h, s, l, a }` with `h ∈ [0, 360)`, `s ∈ [0, 1]`, `l ∈ [0, 1]`, `a ∈ [0, 255]` (alpha as the original byte). Useful for theme tweaking (rotate hue, desaturate, etc.) before round-tripping through hslToHex.

function hexToHsl(hex: string): { a: number; h: number; l: number; s: number }

Convert HSL components back to an ARGB hex string. `h` wraps mod-360, `s` and `l` clamp to `[0, 1]`. `alpha` is the byte (default 255 = opaque), placed in the high byte of the result.

function hslToHex(h: number, s: number, l: number, alpha?: number): string

Lighten a color by mixing it with white. `amount` is in `[0, 1]`: 0 returns the input unchanged, 1 returns pure white. Alpha channel is preserved. Equivalent to `mixColors(hex, 'FFFFFFFF', amount)`.

function lighten(hex: string, amount: number): string

Compute the relative luminance of an ARGB / RGB hex string per the WCAG 2.x formula. Returns a value in `[0, 1]` where 0 is black and 1 is white. The alpha channel (if present) is ignored.

function luminance(hex: string): number

Linearly interpolate between two ARGB colors. `t = 0` returns `hexA`; `t = 1` returns `hexB`; intermediate values mix per channel (including alpha).

function mixColors(hexA: string, hexB: string, t: number): string

Normalise an aRGB hex string. Accepts either 6 or 8 hex digits; 6-digit input is padded to 8 by prefixing `00` (alpha=0 = fully opaque per Excel convention). Returns the canonical uppercase form.

function normaliseRgb(value: string): string

Pick the higher-contrast text color (`'FF000000'` black or `'FFFFFFFF'` white) for a background hex. Useful when applying a solid fill and wanting the cell text to stay readable.

function pickReadableTextColor(backgroundHex: string): "FF000000" | "FFFFFFFF"

Resolve `indexed` references against COLOR_INDEX. Returns undefined for 64/65 (system fg/bg, not in the palette) or out-of-range.

function resolveIndexedColor(idx: number): string | undefined

Shortcut for the common opaque solid colour.

function rgbColor(hex: string): Color

Rotate the hue of a color by `degrees` (positive = clockwise). Saturation and lightness are preserved; alpha is preserved. Equivalent to `hexToHsl` → adjust `h` → `hslToHex`.

function rotateHue(hex: string, degrees: number): string

Add a Border to the pool, returning its 0-based index. Idempotent.

function addBorder(ss: Stylesheet, border: Border): number

Add a CellXf to the cellStyleXfs pool. Idempotent.

function addCellStyleXf(ss: Stylesheet, xf: CellXf): number

Add a CellXf to the cellXfs pool, returning its 0-based index. Idempotent.

function addCellXf(ss: Stylesheet, xf: CellXf): number

Add a Fill to the pool, returning its 0-based index. Idempotent.

function addFill(ss: Stylesheet, fill: Fill): number

Add a Font to the pool, returning its 0-based index. Idempotent.

function addFont(ss: Stylesheet, font: Font): number

Resolve a number-format string to its numFmtId. - Built-in codes return their canonical OOXML ID. - Otherwise the custom code is registered (and allocated an ID ≥ BUILTIN_FORMATS_MAX_SIZE). Idempotent.

function addNumFmt(ss: Stylesheet, formatCode: string): number

Convenience: build the default `cellXfs[0]` Excel emits — points at the workbook's font 0 / fill 0 / border 0 / numFmtId 0 (General).

function defaultCellXf(): CellXf

Read-only snapshot of every Border entry in the pool, indexed by id.

function listBorders(ss: Stylesheet): readonly Border[]

Read-only snapshot of every CellStyleXf entry (named-style xfs).

function listCellStyleXfs(ss: Stylesheet): readonly CellXf[]

Read-only snapshot of every CellXf entry in the cellXfs pool.

function listCellXfs(ss: Stylesheet): readonly CellXf[]

Read-only snapshot of every Fill entry in the pool, indexed by id.

function listFills(ss: Stylesheet): readonly Fill[]

Read-only snapshot of every Font entry in the pool, indexed by id.

function listFonts(ss: Stylesheet): readonly Font[]

Build a fresh Stylesheet pre-populated with Excel's required default entries. Mirrors openpyxl's empty Stylesheet: fonts: [DEFAULT_FONT] (index 0) fills: [DEFAULT_EMPTY_FILL, DEFAULT_GRAY_FILL] (indices 0, 1 — required) borders: [DEFAULT_BORDER] (index 0) cellXfs: empty (indices allocated on demand)

function makeStylesheet(): Stylesheet

Translate a Border to a CSS-property record suitable for HTML preview. Each present side becomes `border-<edge>: <width> <style> <#color>`. Theme/auto/missing colours fall back to `currentColor`. Diagonal / vertical / horizontal sides are skipped (CSS has no native equivalent for in-cell strokes). Empty Border returns `{}`.

function borderToCss(border: Border | undefined): Record<string, string>

Build an immutable Border.

function makeBorder(opts?: Partial<Border>): Border

Build an immutable Side.

function makeSide(opts?: Partial<Side>): Side

Translate a Fill to a CSS-property record suitable for HTML preview. `'solid'` PatternFill renders as `background-color`, other pattern types collapse to bgColor (CSS has no built-in equivalent of Excel hatch patterns). GradientFill emits a CSS `background-image` with `linear-gradient(<angle>, …)` for `type='linear'` or `radial-gradient(circle, …)` for `type='path'`. theme/auto colours and unresolvable inputs are skipped (returns `{}`) so callers can spread without overwriting upstream defaults.

function fillToCss(fill: Fill | undefined): Record<string, string>

Single-arg constructor that defers to the variant-specific maker based on `kind`. Useful when the caller has a plain object in hand and wants the freeze invariant applied uniformly.

function makeFill(opts: Partial<PatternFill> | Partial<GradientFill>): Fill

Translate a Font to a CSS-property record suitable for HTML rendering / preview. Boolean toggles map to weight/style/decoration, `size` becomes `font-size: <n>pt`, and an explicit rgb/indexed `color` is rendered as `#RRGGBB` (alpha dropped). theme/auto colours are skipped — callers without a theme can't resolve them. `vertAlign='superscript'|'subscript'` lowers `font-size` to 0.83em (W3C convention) and sets `vertical-align`. Returns `{}` for an empty Font so callers can spread it without overwriting upstream defaults.

function fontToCss(font: Font | undefined): Record<string, string>

Excel's default cell font: Calibri 11, minor scheme, theme=1 colour.

const DEFAULT_FONT: Font

Register a NamedStyle on the Stylesheet: 1. add Font / Fill / Border / NumberFormat to their pools 2. push a CellXf with apply* flags into cellStyleXfs 3. append a {name, xfId, builtinId} entry into the workbook's namedStyles list (caller-managed; this function returns the xfId so callers can connect the dots) Idempotent on (name): re-registering by the same name returns the cached xfId.

function addNamedStyle(ss: Stylesheet, style: NamedStyle): number

Register a built-in style with the supplied Stylesheet (idempotent). Returns the cellStyleXfs index. Throws OpenXmlSchemaError when the name is unknown.

function ensureBuiltinStyle(ss: Stylesheet, name: string): number

Curated subset of openpyxl's `styles` dict. Keys match the user-visible names.

const BUILTIN_NAMED_STYLES: Readonly<Record<string, NamedStyle>>

Translate an Alignment to a CSS-property record suitable for HTML preview. `horizontal` → `text-align`, `vertical` → `vertical-align` (table-cell semantics), `wrapText` → `white-space: pre-wrap`, `textRotation` → `transform: rotate(<-deg>)` (Excel rotates counter-clockwise relative to CSS) plus `transform-origin` to keep the text anchored, and `indent` → `padding-left: <n>em`. `255` stacked-text rotation maps to a 180° flip with `writing-mode`. Empty / undefined Alignment returns `{}`.

function alignmentToCss(alignment: Alignment | undefined): Record<string, string>

Add a DifferentialStyle to the stylesheet's `dxfs` pool. Returns the 0-based index. Idempotent on structural equality (via stableStringify).

function addDxf(ss: Stylesheet, dxf: DifferentialStyle): number