@json-to-office/shared 1.2.0 → 1.3.0

package/dist/rendering/index.d.ts

@@ -1,210 +1,206 @@
+export { F as FeatureRequirement, a as FeatureRequirementCollector, O as OfficeFormat, b as OfficeRenderer, R as RenderOptions, c as RendererDiagnostic, d as RendererDiagnosticSeverity, e as RendererRegistry, U as UnknownRendererError, f as UnsupportedRendererFeatureError, g as UnsupportedRendererFeatureErrorInit, h as assertNever, i as assertRendererSupports, j as diagnoseUnsupportedFeatures, p as partitionDiagnostics, r as rendererError, k as rendererWarning } from '../capabilities-DrHJ6_4G.js';
+
 /**
- * Format-independent renderer contracts.
- *
- * This module deliberately knows nothing about DOCX or PPTX semantics. Each
- * format owns its own intermediate representation (`DocxIR`, `PptxIR`) and its
- * own feature union; the only thing shared between them is the shape of the
- * contract a backend adapter must satisfy.
- *
- * Do not add format-specific feature names, IR nodes or units here.
- */
-/** The Office formats this repository can produce. */
-type OfficeFormat = 'docx' | 'pptx';
-/**
- * Options every renderer accepts.
- *
- * `deterministic` asks the adapter (and the packaging step after it) to make
- * output byte-stable across runs: fixed zip entry timestamps, fixed core
- * metadata timestamps, no random identifiers.
- *
- * `generatedAt` pins the timestamp written into package metadata. Callers that
- * want reproducible bytes pass both.
- */
-interface RenderOptions {
-    deterministic?: boolean;
-    generatedAt?: Date;
-}
-/**
- * A backend that turns a format-specific IR into package bytes.
- *
- * @typeParam TIR - the format's intermediate representation (plain data)
- * @typeParam TFeature - the format's feature union (see `capabilities.ts`)
- * @typeParam TId - the string-literal union of renderer ids for the format
+ * The half of a native chart `@office-open` does not write.
+ *
+ * Both `@office-open/docx` and `@office-open/pptx` build their chart XML with
+ * the same `chartSpaceDesc` out of `@office-open/core`, and both forward only a
+ * subset of `ChartSpaceOptions` from their chart element. Verified against the
+ * packages rather than their types, because `ChartOptions extends
+ * ChartSpaceOptions` promises far more than either adapter reads. What gets
+ * dropped is identical in both formats, and all of it is visible to whoever
+ * opens the file:
+ *
+ * - **No `c:externalData`.** Neither backend writes one, and every `<c:f>`
+ *   comes out empty, so the chart caches its values with no source for them and
+ *   "Edit Data" fails. This is the exact defect the pptx adapter refused native
+ *   charts over.
+ * - **No series colours.** Neither `ChartSeriesCommon` nor `DataPointOptions`
+ *   carries a fill, and `colorMappingOverride` is not forwarded, so every
+ *   series draws in the reader's default palette and ignores the theme.
+ * - **No axis titles.** Neither backend writes one: docx drops the `axes`
+ *   option, and pptx accepts it but cannot be given one without inventing the
+ *   axis ids its plot area references.
+ * - **No legend position**, on docx only — pptx forwards it.
+ * - **No grouping.** `ChartSpaceOptions` has no field for it and
+ *   `chartSpaceDesc` writes `clustered` unconditionally, so a stacked chart
+ *   came out side by side.
+ *
+ * So this module writes them, as pure string transforms over the emitted chart
+ * part plus the XML of the workbook it points at. Editing another library's
+ * serialisation is not free and is chosen deliberately: the alternative is a
+ * chart that draws and then fails on the first double-click.
+ *
+ * Format-neutral on purpose. A `c:chartSpace` is DrawingML, identical in a
+ * .docx and a .pptx; only the *packaging* differs — part paths, relationship
+ * files, content types, and which ZIP library the core happens to use. Those
+ * stay in each core; everything here is shared, which is what keeps the two
+ * formats from drifting into two different answers to the same problem.
+ *
+ * Nothing here touches a ZIP, a clock or a counter, so this package needs no
+ * new dependency and the same series always produce the same bytes.
  */
-interface OfficeRenderer<TIR, TFeature extends string, TId extends string> {
-    readonly id: TId;
-    readonly format: OfficeFormat;
-    readonly capabilities: ReadonlySet<TFeature>;
-    render(document: TIR, options?: RenderOptions): Promise<Uint8Array>;
+/** The sheet a chart's cell references name. */
+declare const CHART_WORKBOOK_SHEET_NAME = "Sheet1";
+/** The relationship type an embedded workbook is attached by. */
+declare const CHART_PACKAGE_RELATIONSHIP = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/package";
+/** The content type of an embedded chart workbook. */
+declare const CHART_WORKBOOK_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+/** One resolved series, as both formats' IR carries it by the time it gets here. */
+interface ChartPartSeries {
+    name?: string;
+    labels: readonly string[];
+    values: readonly number[];
 }
 /**
- * Exhaustiveness guard for discriminated-union switches.
- *
- * Reaching this at runtime means an IR node kind was added without a matching
- * `case`, so it throws rather than silently dropping content.
- */
-declare function assertNever(value: never, context?: string): never;
-
-/**
- * Diagnostics raised when an IR asks a renderer for something it cannot do.
+ * Everything the splice needs, in neither format's vocabulary.
  *
- * These are distinct from `GenerationWarning` (see `../types/warnings`), which
- * describes authoring problems found while building the document. A renderer
- * diagnostic describes a *backend* limitation: the document is fine, this
- * particular adapter just cannot express part of it.
+ * Each core adapts its own IR node to this rather than this module learning
+ * about `DocxIrChartRun` and `PptxIrChartElement`, which would make a shared
+ * module depend on both cores it exists to serve.
  */
-type RendererDiagnosticSeverity = 'error' | 'warning';
 /**
- * One unsupported (or degraded) feature at one place in the IR.
+ * What an authored axis asks for, in neither format's vocabulary.
  *
- * `path` is an IR path such as `slides[2].elements[0].fill` — not an author-JSON
- * path — because the check runs against compiled IR. Compilers record the
- * authoring path alongside where it is useful for the message text.
+ * Every field here is one a backend drops: `AxisOptions` cannot be passed to
+ * `@office-open` at all — supplying `axes` replaces the default pair and needs
+ * `id`/`crossAxisId` values an adapter cannot safely allocate — so an authored
+ * axis is applied by rewriting the axis the backend built.
  */
-interface RendererDiagnostic<TFeature extends string = string> {
-    feature: TFeature;
-    path: string;
-    severity: RendererDiagnosticSeverity;
-    message: string;
+/** Font family, size, weight and colour on one piece of chart text. */
+interface ChartTextStyle {
+    fontFamily?: string;
+    /** Points. */
+    fontSize?: number;
+    bold?: boolean;
+    /** 6-digit hex, no `#`. */
+    color?: string;
 }
-interface UnsupportedRendererFeatureErrorInit<TFeature extends string = string> {
-    format: OfficeFormat;
-    rendererId: string;
-    diagnostics: readonly RendererDiagnostic<TFeature>[];
+interface ChartAxisEdits {
+    title?: string;
+    /** The font of this axis' tick labels. */
+    labelFont?: ChartTextStyle;
+    /** `c:delete`: an axis hidden entirely. */
+    hidden?: boolean;
+    /** `false` draws no axis line, leaving its labels. */
+    lineVisible?: boolean;
+    /** Label rotation, in degrees. */
+    labelRotation?: number;
+    gridLine?: {
+        style?: string;
+        size?: number;
+        color?: string;
+    };
+    /** Value-axis bounds; ignored on a category axis, which has no scale. */
+    min?: number;
+    max?: number;
+    majorUnit?: number;
+    /** A number format code, e.g. `#,##0`. */
+    numberFormat?: string;
 }
-/**
- * Aggregated failure thrown *before* rendering starts.
- *
- * One error carries every unsupported feature found in the IR so a caller sees
- * the whole gap at once instead of fixing them one render at a time.
- */
-declare class UnsupportedRendererFeatureError<TFeature extends string = string> extends Error {
-    readonly code = "UNSUPPORTED_RENDERER_FEATURE";
-    readonly format: OfficeFormat;
-    readonly rendererId: string;
-    /** Distinct unsupported features, in first-seen order. */
-    readonly features: readonly TFeature[];
-    /** Distinct IR paths that required them, in first-seen order. */
-    readonly paths: readonly string[];
-    /** Every error-severity diagnostic that produced this failure. */
-    readonly diagnostics: readonly RendererDiagnostic<TFeature>[];
-    constructor(init: UnsupportedRendererFeatureErrorInit<TFeature>);
+interface ChartPartInput {
+    /** The chart type, in `@office-open`'s spelling. Decides fill vs stroke. */
+    chartType: string;
+    series: readonly ChartPartSeries[];
+    /** Resolved series colours, uppercase 6-digit hex without `#`. May be empty. */
+    colors: readonly string[];
+    categoryAxis?: ChartAxisEdits;
+    valueAxis?: ChartAxisEdits;
+    /** Series line width in points. Only meaningful where the series is a line. */
+    lineWidthPoints?: number;
+    /** An outline on filled data elements: bars, areas and slices. */
+    dataBorder?: {
+        widthPoints: number;
+        color: string;
+    };
+    /** `standard`, `marker` or `filled`; a backend may hardcode the first. */
+    radarStyle?: string;
+    titleFont?: ChartTextStyle;
+    legendFont?: ChartTextStyle;
+    dataLabelFont?: ChartTextStyle;
+    legendPosition?: string;
+    /**
+     * `clustered` | `stacked` | `percentStacked`.
+     *
+     * Spliced rather than passed: `ChartSpaceOptions` has no grouping field at
+     * all, and `chartSpaceDesc` writes `clustered` unconditionally. A chart
+     * authored as "% of total" therefore came out as side-by-side bars summing
+     * to nothing — the one dropped option that misrepresents the data rather
+     * than restyling it.
+     */
+    barGrouping?: string;
 }
 /**
- * A renderer id that is not registered for the format asked for.
+ * A spreadsheet column letter: A, B, … Z, AA, AB, …
  *
- * Caller input, not an infrastructure failure — which is the whole reason it is
- * a class with a `code` rather than a bare `Error`. A server matching on the
- * message text could only answer `500`, so an unknown id looked like the
- * service falling over, and a retry looked worth attempting (#263).
+ * One-based, because a spreadsheet is. Written out rather than assumed to stay
+ * under 26 — a chart with 27 series is unusual, not impossible, and the failure
+ * would be a corrupt sheet rather than an error.
  */
-declare class UnknownRendererError extends Error {
-    readonly code = "UNKNOWN_RENDERER";
-    readonly format: OfficeFormat;
-    /** What the caller asked for. */
-    readonly rendererId: string;
-    /** Every id registered for this format, in registration order. */
-    readonly availableIds: readonly string[];
-    constructor(format: OfficeFormat, rendererId: string, availableIds: readonly string[]);
-}
-/** Build a `RendererDiagnostic` with `severity: 'error'`. */
-declare function rendererError<TFeature extends string>(feature: TFeature, path: string, message: string): RendererDiagnostic<TFeature>;
-/** Build a `RendererDiagnostic` with `severity: 'warning'`. */
-declare function rendererWarning<TFeature extends string>(feature: TFeature, path: string, message: string): RendererDiagnostic<TFeature>;
-/** Split diagnostics into blocking errors and non-blocking warnings. */
-declare function partitionDiagnostics<TFeature extends string>(diagnostics: readonly RendererDiagnostic<TFeature>[]): {
-    errors: RendererDiagnostic<TFeature>[];
-    warnings: RendererDiagnostic<TFeature>[];
-};
-
+declare function columnLetter(index: number): string;
 /**
- * Capability checking: what an IR *requires* versus what an adapter *provides*.
+ * The parts of the xlsx a chart's `c:externalData` points at, in ZIP order.
  *
- * A compiler records one `FeatureRequirement` each time it emits an IR node that
- * needs a backend capability. Before rendering, `assertRendererSupports` diffs
- * those requirements against the adapter's `capabilities` set and throws a
- * single aggregated `UnsupportedRendererFeatureError` if anything is missing.
+ * Returned as XML rather than as a packaged archive: `core-docx` zips with
+ * adm-zip and `core-pptx` with jszip, and a shared module that picked one would
+ * force a second ZIP library into whichever core did not use it. Order is fixed
+ * rather than incidental, so the central directory is a function of the data.
  *
- * The point is that nothing is dropped silently: a feature either appears in the
- * adapter's capability set and is rendered, or it fails loudly before bytes are
- * produced.
+ * Deliberately minimal — five parts, one sheet, inline strings rather than a
+ * shared-string table. A chart workbook is written once and read by one
+ * consumer, so the compression a shared-string table buys is not worth a part
+ * whose indices are one more thing to keep in step with the cells.
  */
-/** One capability an IR node needs, and where in the IR it was needed. */
-interface FeatureRequirement<TFeature extends string = string> {
-    feature: TFeature;
-    /** IR path, e.g. `sections[0].children[3].image`. */
-    path: string;
-    /** Optional detail folded into the failure message. */
-    detail?: string;
-}
+declare function chartWorkbookParts(series: readonly ChartPartSeries[]): ReadonlyArray<readonly [path: string, xml: string]>;
 /**
- * Accumulates feature requirements during compilation.
+ * The cell range one series' values occupy, as a chart reference.
  *
- * Deliberately per-compilation (never module-global) so concurrent generations
- * never share state.
+ * The chart XML and the sheet have to agree on this exactly; deriving both from
+ * one function is what keeps them from drifting apart.
  */
-declare class FeatureRequirementCollector<TFeature extends string> {
-    private readonly requirements;
-    private readonly seen;
-    /**
-     * Record that `feature` is needed at `path`.
-     *
-     * Duplicate (feature, path) pairs collapse, so a compiler can call this
-     * unconditionally inside a loop without inflating the diagnostics.
-     */
-    require(feature: TFeature, path: string, detail?: string): void;
-    /** Every recorded requirement, in first-seen order. */
-    list(): readonly FeatureRequirement<TFeature>[];
-    /** Distinct required features, in first-seen order. */
-    features(): readonly TFeature[];
-    /** True when nothing has been required yet. */
-    isEmpty(): boolean;
-}
+declare function seriesValueReference(seriesIndex: number, pointCount: number): string;
+/** The cell range the category labels occupy. */
+declare function categoryReference(pointCount: number): string;
+/** The single cell holding one series' name. */
+declare function seriesNameReference(seriesIndex: number): string;
+/** The relationship part attaching one workbook to one chart. */
+declare function chartWorkbookRelsXml(workbookName: string): string;
 /**
- * Diff required features against a capability set.
+ * Rewrite one emitted `chartN.xml` with everything the backend omitted.
  *
- * Returns one error-severity diagnostic per unsupported requirement. An empty
- * array means the renderer can render the IR.
- */
-declare function diagnoseUnsupportedFeatures<TFeature extends string>(required: readonly FeatureRequirement<TFeature>[], capabilities: ReadonlySet<TFeature>, rendererId: string): RendererDiagnostic<TFeature>[];
-/**
- * Throw one aggregated error if the renderer is missing any required feature.
+ * Every repair is guarded on what the XML actually lacks, because the two
+ * backends omit different amounts. `@office-open/pptx` hands its whole options
+ * object to `chartSpaceDesc`, so the legend position survives;
+ * `@office-open/docx` forwards eight named fields and loses it. Everything else
+ * here — the cell references behind `<c:f/>`, the series fill, the axis titles,
+ * the grouping and `c:externalData` — is missing from both.
  *
- * Call this after compiling to IR and before handing the IR to an adapter.
+ * Detecting rather than assuming is also what keeps this honest if a backend
+ * starts emitting more: the repair simply stops firing, instead of writing a
+ * second copy of an element a reader would offer to repair.
+ *
+ * `relationshipId` names the workbook relationship in the chart part's own
+ * rels file, which each core writes alongside.
  */
-declare function assertRendererSupports<TFeature extends string>(required: readonly FeatureRequirement<TFeature>[], renderer: Pick<OfficeRenderer<unknown, TFeature, string>, 'id' | 'format' | 'capabilities'>): void;
+declare function spliceChartXml(chartXml: string, chart: ChartPartInput, relationshipId?: string): string;
+declare function chartPartSignature(chartXml: string): string;
+/** The same signature, computed from the IR node the part was emitted from. */
+declare function chartInputSignature(chart: ChartPartInput): string;
 /**
- * A registry of renderers for a single format.
- *
- * Instances are created per format module, not per generation, and hold only
- * immutable adapter descriptors — never per-document state.
+ * Pair emitted chart parts with the inputs they came from, by content.
+ *
+ * Returns one entry per part that matched, in part order. A part with no match
+ * is left out rather than guessed at: the package holds a chart this pass did
+ * not emit, and repairing it from the wrong node is exactly the defect the
+ * matching exists to prevent. Two charts identical in every cached value match
+ * interchangeably, which is harmless — identical data yields an identical
+ * workbook, and an author who wrote two identical charts did not distinguish
+ * their palettes either.
  */
-declare class RendererRegistry<TIR, TFeature extends string, TId extends string> {
-    private readonly format;
-    private readonly defaultId;
-    private readonly renderers;
-    constructor(format: OfficeFormat, defaultId: TId);
-    /**
-     * Register a lazily-constructed renderer.
-     *
-     * The factory is async and only invoked on selection, so an adapter whose
-     * backend is an optional dependency is never imported unless it is chosen.
-     */
-    register(id: TId, factory: () => Promise<OfficeRenderer<TIR, TFeature, TId>>): void;
-    /** Renderer ids registered for this format, in registration order. */
-    ids(): readonly TId[];
-    /** The id used when a caller does not pass one. */
-    getDefaultId(): TId;
-    has(id: string): id is TId;
-    /**
-     * Resolve a renderer, defaulting when `id` is omitted.
-     *
-     * An unknown id is `UnknownRendererError`, which carries the id asked for and
-     * the ones that exist, so a caller boundary can answer "bad request" rather
-     * than "the server broke". A missing optional dependency is re-thrown with an
-     * actionable install hint.
-     */
-    resolve(id?: TId): Promise<OfficeRenderer<TIR, TFeature, TId>>;
-}
+declare function matchChartParts<T extends ChartPartInput>(parts: ReadonlyArray<readonly [ordinal: number, xml: string]>, charts: readonly T[]): Array<{
+    ordinal: number;
+    xml: string;
+    chart: T;
+}>;
 
-export { type FeatureRequirement, FeatureRequirementCollector, type OfficeFormat, type OfficeRenderer, type RenderOptions, type RendererDiagnostic, type RendererDiagnosticSeverity, RendererRegistry, UnknownRendererError, UnsupportedRendererFeatureError, type UnsupportedRendererFeatureErrorInit, assertNever, assertRendererSupports, diagnoseUnsupportedFeatures, partitionDiagnostics, rendererError, rendererWarning };
+export { CHART_PACKAGE_RELATIONSHIP, CHART_WORKBOOK_CONTENT_TYPE, CHART_WORKBOOK_SHEET_NAME, type ChartAxisEdits, type ChartPartInput, type ChartPartSeries, type ChartTextStyle, categoryReference, chartInputSignature, chartPartSignature, chartWorkbookParts, chartWorkbookRelsXml, columnLetter, matchChartParts, seriesNameReference, seriesValueReference, spliceChartXml };

package/dist/rendering/index.js

@@ -1,25 +1,51 @@
 import {
+  CHART_PACKAGE_RELATIONSHIP,
+  CHART_WORKBOOK_CONTENT_TYPE,
+  CHART_WORKBOOK_SHEET_NAME,
   FeatureRequirementCollector,
   RendererRegistry,
   UnknownRendererError,
   UnsupportedRendererFeatureError,
   assertNever,
   assertRendererSupports,
+  categoryReference,
+  chartInputSignature,
+  chartPartSignature,
+  chartWorkbookParts,
+  chartWorkbookRelsXml,
+  columnLetter,
   diagnoseUnsupportedFeatures,
+  matchChartParts,
   partitionDiagnostics,
   rendererError,
-  rendererWarning
-} from "../chunk-JM5KTMNL.js";
+  rendererWarning,
+  seriesNameReference,
+  seriesValueReference,
+  spliceChartXml
+} from "../chunk-BJNBJSQG.js";
 export {
+  CHART_PACKAGE_RELATIONSHIP,
+  CHART_WORKBOOK_CONTENT_TYPE,
+  CHART_WORKBOOK_SHEET_NAME,
   FeatureRequirementCollector,
   RendererRegistry,
   UnknownRendererError,
   UnsupportedRendererFeatureError,
   assertNever,
   assertRendererSupports,
+  categoryReference,
+  chartInputSignature,
+  chartPartSignature,
+  chartWorkbookParts,
+  chartWorkbookRelsXml,
+  columnLetter,
   diagnoseUnsupportedFeatures,
+  matchChartParts,
   partitionDiagnostics,
   rendererError,
-  rendererWarning
+  rendererWarning,
+  seriesNameReference,
+  seriesValueReference,
+  spliceChartXml
 };
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@json-to-office/shared",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Format-agnostic shared types, schemas and validation utilities",
   "type": "module",
   "main": "dist/index.js",