@cj-tech-master/excelts 9.4.2 → 9.5.0

package/dist/browser/modules/excel/chart/chart-utils.d.ts

@@ -0,0 +1,306 @@
+/**
+ * Shared helpers for the chart preview renderers.
+ *
+ * Both `chart-renderer.ts` (classic `c:chart`) and
+ * `chart-ex-renderer.ts` (ChartEx `cx:chart`) used to carry their own
+ * copies of the same handful of math / colour / formatting helpers. The
+ * duplicates had drifted over time — subtle differences in NaN guards,
+ * hex normalisation, theme palettes, etc. — so a fix in one file
+ * silently left the other buggy. This module is the single authoritative
+ * home for the helpers shared between the two renderers (plus a few
+ * internals — `escapeXml`, `escapeXmlAttr` — that had identical copies
+ * scattered across the chart pipeline).
+ *
+ * Design constraints:
+ *
+ *   - **Zero dependencies on chart-renderer / chart-ex-renderer** so
+ *     this module sits below them in the import graph and does not
+ *     create cycles. Types-only imports from `./types` are fine.
+ *   - **Behaviour-preserving** compared with the consolidated
+ *     implementations. The old files had two classes of helper:
+ *     (1) strictly identical duplicates and (2) near-duplicates where
+ *     one version was more defensive than the other. For the latter we
+ *     kept the defensive variant — graceful degradation on malformed
+ *     input is always the safer choice for a preview path.
+ *   - **Structural rect typing**. The renderers use two different
+ *     concrete rect types (`ChartSceneRect` in chart-renderer,
+ *     `SvgRect` in chart-ex-renderer) that share the same shape.
+ *     Helpers here take structural `{ x: number; y: number; width:
+ *     number; height: number }` so both renderers can call them
+ *     directly without adapters.
+ */
+import type { ChartColor, ChartFill, ChartLine } from "./types.js";
+/**
+ * RGB(A) colour triple used by the chart PDF bridge. `a` is optional and
+ * defaults to 1 (fully opaque); surfaces that implement transparency
+ * (e.g. `@pdf/builder` `PdfPageBuilder`) materialise `a < 1` as an
+ * `/ExtGState` resource and emit the corresponding `gs` operator. Older
+ * surfaces that ignore `a` render as opaque, which matches the
+ * pre-alpha behaviour exactly.
+ *
+ * Lives in `chart-utils.ts` so both renderers can produce values
+ * independently; `chart-renderer.ts` re-exports the type to keep the
+ * public surface (`@excel/chart` index / external consumers) stable.
+ */
+export interface PdfColor {
+    r: number;
+    g: number;
+    b: number;
+    a?: number;
+}
+/**
+ * Structural rect type for helper functions. Both `ChartSceneRect`
+ * (chart-renderer.ts) and the ChartEx renderer's private `SvgRect`
+ * are assignable to this.
+ */
+export interface ChartRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Default SVG / PNG / PDF canvas width when the caller omits `options.width`. */
+export declare const DEFAULT_WIDTH = 640;
+/** Default SVG / PNG / PDF canvas height when the caller omits `options.height`. */
+export declare const DEFAULT_HEIGHT = 360;
+/**
+ * Default series colour rotation. Matches the Excel 2019+ Office theme
+ * accent1..accent6 palette so a brand-new workbook with no theme XML
+ * still renders with the colours Excel would have used.
+ */
+export declare const COLORS: string[];
+/** Dark grey for axis lines / frame strokes. */
+export declare const AXIS_COLOR = "#444444";
+/** Light grey for gridlines. */
+export declare const GRID_COLOR = "#D9D9D9";
+/**
+ * Convert a theme-palette index (`ChartColor.theme`) back to its
+ * DrawingML `schemeClr` token. Out-of-range indices fall back to
+ * `"dk1"` so a malformed model still produces parseable XML Excel
+ * renders as the first theme slot rather than XML that contains an
+ * `undefined` literal.
+ */
+export declare function themeIndexToName(index: number): string;
+/**
+ * Clamp to the closed interval `[0, 1]`. Non-finite input collapses to
+ * `0` rather than propagating `NaN` — downstream callers use the
+ * result as an interpolation parameter where `NaN` would paint black.
+ */
+export declare function clamp01(value: number): number;
+/**
+ * Map a data-space value onto the plot area's y coordinate space (SVG
+ * y grows downward, so large `value` ends up near the top of the
+ * plot). Guards against `max === min` — a single-point dataset or a
+ * range that collapsed for any reason would otherwise produce `NaN`.
+ */
+export declare function valueToY(value: number, min: number, max: number, plot: {
+    y: number;
+    height: number;
+}): number;
+/**
+ * Map a data-space value onto the plot area's x coordinate space. Same
+ * `max === min` guard as {@link valueToY}.
+ */
+export declare function valueToX(value: number, min: number, max: number, plot: {
+    x: number;
+    width: number;
+}): number;
+/** Convert polar `(radius, angle)` to Cartesian around `(cx, cy)`. */
+export declare function polar(cx: number, cy: number, radius: number, angle: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Shrink a rect by `amount` on each side (uniform inset). Non-finite
+ * inputs collapse to zero on all four components rather than
+ * propagating `NaN` — `Math.max(0, NaN)` returns `NaN` per ECMAScript,
+ * and a `NaN` width feeding downstream math (e.g. `valueToX`) cascades
+ * into every rendered coordinate.
+ */
+export declare function insetRect<T extends ChartRect>(rect: T, amount: number): ChartRect;
+/**
+ * Format a number for SVG attribute values and inline XML. Two-decimal
+ * precision with trailing `.00` stripped (`1.00 → "1"`, `1.50 →
+ * "1.50"` — we intentionally keep the second zero to avoid widening the
+ * diff against Excel's own byte output on round-trips). Non-finite
+ * input returns `"0"` — `Number.toFixed(NaN)` produces the literal
+ * string `"NaN"`, which is invalid inside SVG attribute values and
+ * breaks downstream parsers.
+ */
+export declare function fmt(value: number): string;
+/**
+ * Format a numeric attribute value for XML emission. Returns an empty
+ * string for `undefined` / `NaN` / `±Infinity` — non-finite values would
+ * otherwise serialise as literal `"NaN"` / `"Infinity"` text, which no
+ * XSD validator accepts as `xsd:double` and downstream parsers reject.
+ * Emit an empty string so the caller's attribute-inclusion guard
+ * (`if (attrs.length > 0)` or explicit `!== undefined` check) drops
+ * the attribute entirely rather than stamping garbage into the wire
+ * format.
+ *
+ * Uses JavaScript's default `toString()` which is round-trip-safe per
+ * IEEE 754 (no precision drift) for both integer and fractional input.
+ */
+export declare function fmtNumAttr(value: number | undefined): string;
+/**
+ * Format a numeric text-node value. Same semantics as {@link fmtNumAttr},
+ * but for use inside element content (e.g. `<cx:pt>42.5</cx:pt>`).
+ * Non-finite values become `"0"` — a text node must be non-empty to
+ * keep the element well-formed, and `0` is the least-surprising
+ * fallback for a blank / error cell (matches how most OOXML readers
+ * treat empty numeric `<c:v>`).
+ */
+export declare function fmtNumText(value: number): string;
+/**
+ * Format a number for user-visible axis tick labels.
+ *
+ *   - Integer values → plain digits (`42` → `"42"`).
+ *   - `|value| < 0.01` but non-zero → scientific notation with three
+ *     significant figures (`1.00e-3`). Two-decimal mantissa keeps the
+ *     label compact while preserving enough precision that tick values
+ *     remain distinguishable; a single-digit mantissa would collapse
+ *     consecutive ticks like `1.1e-3` and `1.4e-3` to the same label.
+ *   - Otherwise → single decimal (`toFixed(1)`).
+ *   - Non-finite input → `""` (tick position still drawn without
+ *     label, keeping the chart legible while flagging the upstream
+ *     computation bug on inspection).
+ *
+ * This is the "axis-label" formatter — it's intentionally compact and
+ * does not apply OOXML number formats. Callers that need the authored
+ * format code should resolve it upstream.
+ */
+export declare function formatNumber(value: number): string;
+/**
+ * Escape XML text content — `&`, `<`, `>` become `&amp;`, `&lt;`,
+ * `&gt;` respectively. XML-illegal characters are stripped up front
+ * via the shared {@link stripXmlIllegalChars} helper — that covers
+ * the forbidden C0 controls (`0x00-0x08 | 0x0B | 0x0C | 0x0E-0x1F`),
+ * DEL (`0x7F`, project-policy strip despite being technically legal
+ * XML), lone UTF-16 surrogate halves, and the `0xFFFE` / `0xFFFF`
+ * noncharacters.
+ *
+ * Apostrophe and double-quote pass through unescaped — both are legal
+ * inside text content and leaving them alone preserves Excel's byte
+ * output (`<c:name>'Sheet'!Pivot1</c:name>` with literal quotes).
+ *
+ * We keep this separate from {@link xmlEncode} in `@xml/encode`
+ * because that helper escapes all five reserved entities; the chart
+ * module prefers byte-level parity with Excel's own output, which
+ * leaves `'` / `"` alone in text context.
+ */
+export declare function escapeXml(value: string): string;
+export { xmlEncodeAttr as escapeXmlAttr } from "../../xml/encode.js";
+/**
+ * Normalise any supported hex input to a 6-digit uppercase value
+ * (without the leading `#`). Accepts:
+ *
+ *   - 3-digit shorthand `#FFF` → `FFFFFF` (each nibble duplicated).
+ *   - 4-digit shorthand `#FFFA` with alpha → `FFFFFF` (alpha dropped;
+ *     renderer encodes alpha separately).
+ *   - 6-digit `#112233`.
+ *   - 8-digit `#11223344` with alpha → `112233` (alpha dropped).
+ *
+ * Returns `undefined` when the input cannot be coerced — lets callers
+ * fall back to a default colour rather than emit `#NaNNaNNaN`.
+ */
+export declare function normalizeHex6(hex: string | undefined): string | undefined;
+/**
+ * White-blend `hex` by `alpha` — a cheap opacity approximation for
+ * SVG surfaces that don't support per-element `fill-opacity`. Accepts
+ * 3/4/6/8-digit hex; returns the input untouched for anything else
+ * rather than emit `"#NaNNaNNaN"`.
+ */
+export declare function withAlpha(hex: string, alpha: number): string;
+/**
+ * Linearly interpolate between two hex colours. `t` is clamped to
+ * `[0, 1]`; non-finite `t` falls back to `0`. Malformed hex inputs
+ * degrade gracefully (prefer the end colour when `t >= 0.5`; prefer
+ * the start colour otherwise) so one bad input channel never produces
+ * `"#NaNNaNNaN"`.
+ */
+export declare function interpolateColor(a: string, b: string, t: number): string;
+/**
+ * Convert a hex colour string to a {@link PdfColor}. Preserves an
+ * explicit alpha byte when the caller supplied 4- or 8-digit hex —
+ * PDF surfaces that honour `PdfColor.a` (notably `PdfPageBuilder` via
+ * `/ExtGState`) then produce real translucency. Malformed input
+ * degrades to opaque black rather than producing `NaN` channels, which
+ * would emit broken PDF content.
+ */
+export declare function hexToPdfColor(hex: string): PdfColor;
+/**
+ * Like {@link hexToPdfColor} but attaches an explicit alpha value.
+ * Callers use this to mirror the SVG path's `withAlpha(color, 0.35)`
+ * pattern on the PDF bridge: the hex itself stays opaque, `a` carries
+ * the transparency the SVG would paint by white-blending.
+ */
+export declare function hexToPdfColorWithAlpha(hex: string, alpha: number): PdfColor;
+/**
+ * Resolve a {@link ChartColor} into a preview-grade hex colour. Accepts
+ * every DrawingML colour variant Excel emits — `srgb`, `theme` (looked
+ * up in {@link THEME_PREVIEW_PALETTE}), `sysClr` (the two Excel keeps
+ * meaningful in the preview — `windowText` / `window`), and `prstClr`
+ * (the ~140-entry {@link PRESET_COLOR_HEX_TABLE}). Returns `undefined`
+ * when the colour is absent or references something this preview cannot
+ * resolve (an unknown preset / sysClr, or a theme index outside the
+ * 12-entry palette). Callers that need a default coalesce with `??`.
+ *
+ * Shared by fill, line, and text-property resolvers so a file that
+ * sets, say, a gridline colour via `<a:schemeClr val="accent3"/>`
+ * paints the correct accent-3 hex — previously the line/text paths
+ * only honoured `srgbClr` and silently fell back to the renderer's
+ * default grey.
+ *
+ * Colour modifiers (`tint`, `shade`, `lumMod`, `lumOff`, `alpha`,
+ * `satMod`) are intentionally NOT applied — the preview path doesn't
+ * model the DrawingML blend pipeline, and approximating one component
+ * in isolation produces visibly-wrong results. Authors who need
+ * exact theme-derived colours should rasterise with a full DrawingML
+ * renderer.
+ */
+export declare function resolveChartColor(color: ChartColor | undefined): string | undefined;
+/**
+ * Resolve a {@link ChartFill} into a preview-grade hex colour. Recognises
+ * the four `<a:solidFill>` children Excel writes (`srgbClr`, `schemeClr`,
+ * `sysClr`, `prstClr`) via the shared {@link resolveChartColor} resolver
+ * and the {@link THEME_PREVIEW_PALETTE} / {@link PRESET_COLOR_HEX_TABLE}
+ * lookup tables for the theme / preset variants.
+ *
+ * When the fill cannot be resolved (no fill set, empty `solidFill`,
+ * unknown preset / system colour), returns `fallback`. Callers that
+ * want `undefined` for misses should pass `undefined` as the fallback;
+ * callers that want a palette rotation entry should resolve the
+ * fallback themselves and pass it in. This unifies what used to be
+ * two almost-identical helpers (`colorFromShapeFill` in
+ * chart-renderer.ts and `shapeFillColor` in chart-ex-renderer.ts).
+ */
+export declare function previewShapeFillColor<F extends string | undefined>(fill: ChartFill | undefined, fallback: F): F | string;
+/**
+ * Resolve a {@link ShapeProperties.ln} stroke colour to a preview-grade
+ * hex string. Honours every DrawingML colour variant on the line's own
+ * `<a:solidFill>` via {@link resolveChartColor} — previously only
+ * `srgbClr` was read, which silently reverted every theme / preset /
+ * sysClr line colour (gridlines, axes, trendlines, error bars) to the
+ * renderer's default grey on load.
+ */
+export declare function previewShapeLineColor(line: ChartLine | undefined): string | undefined;
+/**
+ * Resolve a {@link ShapeProperties.ln} stroke width (OOXML EMU) to a
+ * preview pixel width. OOXML stores line widths in EMU (1 pt = 12 700
+ * EMU); the preview clamps to a minimum of 0.5 px so a tiny authored
+ * width still renders as a visible stroke.
+ */
+export declare function previewShapeLineWidthPx(line: ChartLine | undefined): number | undefined;
+/**
+ * DrawingML preset colour table (`ST_PresetColorVal` from the OOXML
+ * schema). ~140 named colours — superset of HTML's X11 palette. The
+ * renderers resolve `<a:prstClr val="…"/>` through this table so
+ * template-built workbooks with preset colour references (`darkRed`,
+ * `navy`, `forestGreen`, …) render with the correct hex instead of
+ * rotating through the default series palette.
+ *
+ * Previously this lived on `chart-renderer.ts` and was imported by
+ * `chart-ex-renderer.ts`. Moved here so it sits below both renderers
+ * in the import graph.
+ */
+export declare const PRESET_COLOR_HEX_TABLE: Readonly<Record<string, string>>;