@cj-tech-master/excelts 9.4.2 → 9.5.0

package/dist/types/modules/excel/chart/shape-properties.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Shape property (spPr) and text property (txPr) utilities.
+ *
+ * During chart parsing, spPr and txPr elements are captured as raw XML strings
+ * for perfect round-trip fidelity. These utilities provide structured read/write
+ * access to the most commonly used properties:
+ *
+ * - Fill color (solid sRGB / theme)
+ * - Line/outline color and width
+ * - Font size, bold, italic, color, family
+ *
+ * The approach: parse raw XML on demand using regex extraction (no full DOM),
+ * and generate raw XML from structured models when creating new properties.
+ */
+import type { ShapeProperties, ChartTextProperties, ChartColor, ChartFill, ChartLine } from "./types.js";
+/**
+ * Check if the object is purely a raw XML capture — `_rawXml` is set
+ * and NO structured fields have been populated. The parser produces
+ * dual-state objects (both `_rawXml` and structured) from raw bytes so
+ * downstream consumers get the best of both worlds: cheap byte-perfect
+ * round-trip PLUS typed access. Getters (`getSpPrFillColor` et al.)
+ * must prefer structured when present; setters must NOT reparse from
+ * `_rawXml` because doing so wipes any prior structured mutation.
+ *
+ * Writers must ALSO consult this predicate before short-circuiting to
+ * the raw bytes: if the model has been mutated through a direct
+ * property assignment (`spPr.fill = {...}` without routing through
+ * `setSpPrFill`), the raw bytes are stale and the structured path
+ * must win. Exported for use by `_renderSpPr` in both the classic
+ * chart-space xform and the ChartEx renderer.
+ *
+ * Previously `isRawXml` returned `true` whenever `_rawXml` was a
+ * string, which caused `setSpPrFill` → `parseSpPr` to re-read from
+ * raw and discard pending `line.width` / `fill.solid` assignments.
+ */
+export declare function isRawXmlShape(obj: {
+    _rawXml?: string;
+} | undefined): boolean;
+/**
+ * Whether a `ChartTextProperties` object is a pure raw-XML capture
+ * with no structured fields set. Analogous to {@link isRawXmlShape}
+ * for shape properties: when a caller directly assigns `txPr.color`,
+ * `txPr.size`, etc., the stale `_rawXml` must NOT win — the writer
+ * should fall through to the structured rendering path.
+ */
+export declare function isRawXmlTxPr(obj: {
+    _rawXml?: string;
+} | undefined): boolean;
+/**
+ * Extract structured fill and line properties from a raw spPr XML string.
+ * Returns the structured ShapeProperties if extraction succeeds.
+ */
+export declare function parseSpPr(spPr: ShapeProperties): ShapeProperties;
+/**
+ * Get the solid fill color from a ShapeProperties object.
+ * Works for both raw XML and structured models.
+ */
+export declare function getSpPrFillColor(spPr: ShapeProperties): ChartColor | undefined;
+/**
+ * Get the complete fill (solid / gradient / pattern / noFill) from a
+ * ShapeProperties object. Works for both raw XML and structured models.
+ * Prefer this over {@link getSpPrFillColor} when the caller needs to
+ * distinguish between "no fill", "gradient", etc. — the color-only
+ * accessor collapses all three to `undefined`.
+ */
+export declare function getSpPrFill(spPr: ShapeProperties): ChartFill | undefined;
+/**
+ * Get the line/outline properties from a ShapeProperties object.
+ */
+export declare function getSpPrLine(spPr: ShapeProperties): ChartLine | undefined;
+/**
+ * Get the gradient fill from a ShapeProperties object.
+ */
+export declare function getSpPrGradient(spPr: ShapeProperties): ChartFill["gradient"] | undefined;
+/**
+ * Get the pattern fill from a ShapeProperties object.
+ */
+export declare function getSpPrPattern(spPr: ShapeProperties): ChartFill["pattern"] | undefined;
+/**
+ * Extract structured text properties from a raw txPr XML string.
+ *
+ * Parses the fields the structured {@link ChartTextProperties} model
+ * declares:
+ *   - `size`, `bold`, `italic`, `underline`, `strike`, `cap`, `baseline`,
+ *     `kern`, `spacing`, `lang` (from the first `<a:defRPr>` / `<a:rPr>`)
+ *   - `color` (from `<a:solidFill>` inside the same element)
+ *   - `fontFamily`, `eastAsianFamily`, `complexScriptFamily`
+ *     (from `<a:latin>` / `<a:ea>` / `<a:cs>` children)
+ *   - `rotation` (from `<a:bodyPr/@rot>`)
+ *
+ * Callers that want to preserve every attribute OOXML might carry
+ * (e.g. `spc="100"`, `u="sng"`, `baseline="30000"`) must not rely on
+ * this function round-tripping via structured fields alone — keep the
+ * `_rawXml` on the txPr. This parser is a best-effort structural view
+ * for consumers that want to READ the common properties; `_rawXml`
+ * remains authoritative for write-side fidelity.
+ */
+export declare function parseTxPr(txPr: ChartTextProperties): ChartTextProperties;
+/**
+ * Get font size from a ChartTextProperties object (returns points, e.g. 10).
+ */
+export declare function getTxPrFontSize(txPr: ChartTextProperties): number | undefined;
+/**
+ * Get font color from a ChartTextProperties object.
+ */
+export declare function getTxPrColor(txPr: ChartTextProperties): ChartColor | undefined;
+/**
+ * Get the font family (typeface) declared on `<a:latin>` / `<a:cs>`
+ * within a `txPr` raw or structured object. Returns `undefined` if the
+ * properties do not carry a typeface, in which case renderers should
+ * use their own default.
+ */
+export declare function getTxPrFontFamily(txPr: ChartTextProperties): string | undefined;
+/**
+ * Get the boolean bold flag from a `txPr`'s first `a:defRPr`/`a:rPr`.
+ */
+export declare function getTxPrBold(txPr: ChartTextProperties): boolean | undefined;
+/**
+ * Get the boolean italic flag from a `txPr`'s first `a:defRPr`/`a:rPr`.
+ */
+export declare function getTxPrItalic(txPr: ChartTextProperties): boolean | undefined;
+/**
+ * Build a structured ShapeProperties object, preserving every field that
+ * `parseSpPr` can produce (fill, line, effectList, scene3d, sp3d, transform,
+ * presetGeometry, customGeometry, bwMode).
+ *
+ * Previous versions only copied a five-field subset, which caused
+ * `setSpPrFill` / `setSpPrLine` to silently strip `xfrm` / `prstGeom` /
+ * `custGeom` off the returned spPr whenever the input had been parsed from
+ * raw XML. The earlier `_rawXml` round-trip path was dropped because it lost
+ * effectList/scene3d/sp3d; we now keep all structured fields and intentionally
+ * omit `_rawXml` so that `_renderSpPr` (chart-space-xform) re-emits the spPr
+ * from the structured data.
+ */
+export declare function buildSpPr(props: ShapeProperties): ShapeProperties;
+/**
+ * Build a structured {@link ChartTextProperties} object.
+ *
+ * Returns a plain structured copy (no `_rawXml`) so downstream mutations
+ * (`props.size = 1400`) take effect when the txPr is later serialised.
+ * The writer (`_renderTxPr` / `_renderRunProperties` in
+ * `chart-space-xform.ts`) fully supports structured txPr data and only
+ * falls back to raw XML pass-through when `_rawXml` is present; returning
+ * `_rawXml` here would freeze the txPr and silently discard subsequent
+ * edits, which is a trap API.
+ */
+export declare function buildTxPr(props: ChartTextProperties): ChartTextProperties;
+/**
+ * Modify a property on an existing spPr (raw or structured).
+ * Returns a new ShapeProperties object with the modification applied.
+ */
+export declare function setSpPrFill(spPr: ShapeProperties | undefined, fill: ChartFill): ShapeProperties;
+/**
+ * Modify line properties on an existing spPr.
+ */
+export declare function setSpPrLine(spPr: ShapeProperties | undefined, line: ChartLine): ShapeProperties;

package/dist/types/modules/excel/chart/stroke-font.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Stroke font for chart PNG rasterisation.
+ *
+ * A simplified sans-serif vector font covering ASCII printable characters
+ * (32–126). Each glyph is defined as a sequence of polyline strokes in a
+ * normalised coordinate system where the cap-height is 1.0 and the
+ * em-width is typically 0.6–0.7.
+ *
+ * Coordinates use a top-left origin with Y increasing downward (matching
+ * pixel space). The baseline sits at y = 0.75 (from the top of the em
+ * square). Descenders extend below y = 0.75 to approximately y = 1.0.
+ *
+ * Each glyph entry:
+ *   - `w`: advance width (0–1 scale, relative to fontSize)
+ *   - `d`: array of strokes, each stroke is an array of [x, y] points
+ *
+ * This file has NO imports — it is a pure data module.
+ */
+export interface StrokeGlyph {
+    /** Advance width in em units. */
+    w: number;
+    /** Array of polyline strokes. Each stroke is an array of [x, y] coordinate pairs. */
+    d: number[][][];
+}
+/**
+ * Stroke font glyphs indexed by character code (32–126).
+ *
+ * Design principles:
+ * - Cap height spans y ≈ 0.15 to y ≈ 0.75 (baseline)
+ * - x-height (lowercase) spans y ≈ 0.35 to y ≈ 0.75
+ * - Descenders go to y ≈ 0.95
+ * - Ascenders reach y ≈ 0.15
+ * - All strokes use straight line segments; curves are approximated with
+ *   short segment sequences for a clean sans-serif appearance.
+ */
+export declare const STROKE_FONT: Record<number, StrokeGlyph>;

package/dist/types/modules/excel/chart/topojson.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Minimal, zero-dependency TopoJSON feature extractor.
+ *
+ * TopoJSON (https://github.com/topojson/topojson-specification) encodes
+ * geometries as indices into a shared arc table, optionally with an
+ * integer quantisation grid that is dequantised via `transform`. Full
+ * support (mesh, merge, presimplify…) belongs to a dedicated library;
+ * this module implements only what the `regionMap` renderer needs:
+ *
+ * 1. Parse a {@link TopologyLike} object produced by any TopoJSON 1.x
+ *    emitter (d3, topojson-server, world-atlas bundles).
+ * 2. Dequantise integer-encoded arcs back to absolute lon/lat pairs.
+ * 3. Resolve a geometry (`Polygon` / `MultiPolygon` / `LineString` /
+ *    `MultiLineString` / `Point` / `MultiPoint`) into drawable rings.
+ *
+ * The shapes here mirror what the TopoJSON 1.x spec emits but keep
+ * the types narrow — unknown fields (`bbox`, vendor extensions) are
+ * ignored, not stripped. Users who need the full spec should use the
+ * upstream `topojson-client` package; doing so does not conflict with
+ * this module because both return `[lon, lat]` coordinate arrays in
+ * the geometry output.
+ */
+/** Raw TopoJSON topology as produced by d3 / world-atlas. */
+export interface TopologyLike {
+    type: "Topology";
+    /**
+     * Optional quantisation transform: each arc point's integer pair
+     * `[qx, qy]` is decoded as
+     * `[qx * scale[0] + translate[0], qy * scale[1] + translate[1]]`
+     * after delta-undo. Absent → arcs already hold absolute coordinates.
+     */
+    transform?: {
+        scale: [number, number];
+        translate: [number, number];
+    };
+    /** Shared arc pool; each arc is a list of `[x, y]` integer or float pairs. */
+    arcs: Array<Array<[number, number]>>;
+    /** Named geometry collections (e.g. `countries`, `states`). */
+    objects: Record<string, TopoGeometryCollection | TopoGeometry>;
+}
+export type TopoGeometry = {
+    type: "Polygon";
+    arcs: number[][];
+    id?: string | number;
+    properties?: Record<string, unknown>;
+} | {
+    type: "MultiPolygon";
+    arcs: number[][][];
+    id?: string | number;
+    properties?: Record<string, unknown>;
+} | {
+    type: "LineString";
+    arcs: number[];
+    id?: string | number;
+    properties?: Record<string, unknown>;
+} | {
+    type: "MultiLineString";
+    arcs: number[][];
+    id?: string | number;
+    properties?: Record<string, unknown>;
+} | {
+    type: "Point";
+    coordinates: [number, number];
+    id?: string | number;
+    properties?: Record<string, unknown>;
+} | {
+    type: "MultiPoint";
+    coordinates: Array<[number, number]>;
+    id?: string | number;
+    properties?: Record<string, unknown>;
+};
+export interface TopoGeometryCollection {
+    type: "GeometryCollection";
+    geometries: TopoGeometry[];
+}
+/**
+ * A resolved polygon — an ordered ring of `[lon, lat]` pairs in
+ * absolute coordinates. Holes (inner rings) are represented as
+ * subsequent entries in the outer array.
+ */
+export type ResolvedRing = Array<[number, number]>;
+/**
+ * Resolve a named object from a {@link TopologyLike} into a flat list
+ * of `{ id, rings }` records. Each `rings[0]` is the outer ring and
+ * the remainder are holes. For `LineString` / `MultiLineString`,
+ * `rings` contains the open polylines; the caller is expected to
+ * treat them as un-closed paths.
+ *
+ * Throws if the object is missing or not a recognised geometry type —
+ * preferring a loud failure over silent "empty map" output, which is
+ * almost always a wiring bug on the caller's side.
+ */
+export declare function resolveTopologyObject(topology: TopologyLike, objectName: string): Array<{
+    id: string | number | undefined;
+    properties: Record<string, unknown> | undefined;
+    geometry: TopoGeometry;
+    rings: ResolvedRing[];
+}>;