@nice2dev/ui-diagrams 1.4.14 → 1.4.15

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @nice2dev/ui-diagrams — Changelog
 
+## 1.4.15
+
+### Patch Changes
+
+- 8f06640: OmniVerk wishlist 1.4.0, diagrams:
+
+  - **#5 Export.** One scene now backs every format. Edges run as on the canvas: the geometry moved to
+    the new exported `diagramEdgeShape` and `diagramPortPoint`.
+    - `exportToSvg` draws the canvas's lines and shapes (it drew centre-to-centre lines).
+    - New `exportToPng` draws a real PNG; PNG previously went out as SVG text.
+    - New `exportToPdf` / `sceneToPdf` write a vector PDF with no dependencies.
+      - Paths and Helvetica text, so the PDF stays sharp and its text can be selected.
+      - Polish and other Latin letters are text; a label in another script is an image in a browser.
+      - One fitted page, or tiles over several pages; A4, A3 or Letter, either orientation.
+      - Both return a promise; the PDF writer loads on the first PDF export, so the editor does not carry it.
+    - Also new: `diagramScene` and `sceneToSvg`.
+    - `NiceDiagramEditor`:
+      - takes a `ref` with `export(format)`;
+      - has PDF in the toolbar;
+      - sends PNG and PDF to the new `onExportFile`, or downloads them;
+      - adds an export row in `readOnly` with `showExportInReadOnly`.
+    - `DiagramToolbar`'s `onExport` format adds `'pdf'`.
+  - **#7 Tidy tree.** `autoLayout` `'tree'` is a tidy tree; it used to be the layered layout.
+    - Children keep their edge order and a parent stands over the middle of its children.
+    - Branches never overlap.
+    - `diagramType` now works (it was ignored): `'orgchart'` with `autoLayout` lays out top-down as a
+      tree and draws square-cornered connectors from parent bottom to child top.
+    - New `tidyTreeLayout` in `@nice2dev/ui`.
+  - **#8 `NiceOrganizationChart`.**
+    - A chart wider than its box starts at the left edge and scrolls; centring used to cut off the
+      left part.
+    - Sibling connectors no longer have gaps.
+    - New `zoomable` (zoom out / in, fit), and `exportable` / `onExport` for SVG and PNG drawn from the
+      data.
+    - New `orgChartToSvg` / `orgChartToPng`.
+
 ## 1.4.14
 
 No changes in this release.

package/dist/components/DiagramCanvas.d.ts

@@ -3,6 +3,11 @@ import { AnimationState } from '../core/animationEngine';
 import { ParticleEngineState } from '../core/diagramParticleEngine';
 import { DiagramNode, DiagramEdge, DiagramGroup, DiagramViewport, DiagramThemeOverrides, DiagramViewMode, Point, Size } from '../types/diagramTypes';
 export interface DiagramCanvasProps {
+    /**
+     * Tree connectors (1.4.15, org charts): edges drawn as the default bezier run from the parent's
+     * bottom middle into the child's top middle, square-cornered.
+     */
+    treeEdges?: boolean;
     nodes: readonly DiagramNode[];
     edges: readonly DiagramEdge[];
     groups?: readonly DiagramGroup[];

package/dist/components/DiagramToolbar.d.ts

@@ -14,7 +14,7 @@ export interface DiagramToolbarProps {
     onRedo?: () => void;
     canUndo?: boolean;
     canRedo?: boolean;
-    onExport?: (format: 'svg' | 'mermaid' | 'ndd' | 'png') => void;
+    onExport?: (format: 'svg' | 'mermaid' | 'ndd' | 'png' | 'pdf') => void;
     onZoomIn?: () => void;
     onZoomOut?: () => void;
     onZoomReset?: () => void;

package/dist/components/NiceDiagramEditor.d.ts

@@ -30,8 +30,15 @@ export interface NiceDiagramEditorProps {
     diagramType?: DiagramType;
     /** Fires on every document change */
     onChange?: (doc: Readonly<NiceDiagramDocument>) => void;
-    /** Export callback (called when user exports via toolbar) */
+    /** Export callback (called when user exports via toolbar): the text formats — SVG, Mermaid, .ndd.json. */
     onExport?: (format: string, content: string) => void;
+    /**
+     * The file formats exported from the toolbar (1.4.15): PNG and a vector PDF. Without it the file
+     * downloads. (PNG went to `onExport` as SVG text before.)
+     */
+    onExportFile?: (format: 'png' | 'pdf', file: Blob) => void;
+    /** An export button in `readOnly` too (1.4.15; `ref.export(format)` works either way). */
+    showExportInReadOnly?: boolean;
     /**
      * Language of the editor's own texts. Default: the app's (its global NiceI18nProvider) — it
      * was English whatever the app used, before 1.3.17.
@@ -52,4 +59,9 @@ export interface NiceDiagramEditorProps {
     /** Optional "?" guided tour. Off by default; `true` uses the built-in tour. */
     tutorial?: NiceComponentTutorial;
 }
-export declare const NiceDiagramEditor: React.FC<NiceDiagramEditorProps>;
+/** What a `ref` on NiceDiagramEditor gives (1.4.15 — OmniVerk wishlist #5): the diagram exported. */
+export interface NiceDiagramEditorHandle {
+    /** The diagram in a format: text for SVG, Mermaid and .ndd.json, a file for PNG and PDF. */
+    export(format: 'svg' | 'mermaid' | 'ndd' | 'png' | 'pdf'): Promise<string | Blob>;
+}
+export declare const NiceDiagramEditor: React.ForwardRefExoticComponent<NiceDiagramEditorProps & React.RefAttributes<NiceDiagramEditorHandle>>;

package/dist/core/edgeGeometry.d.ts

@@ -0,0 +1,23 @@
+import { DiagramEdge, DiagramNode, Point } from '../types/diagramTypes';
+/** An edge's path (`M` / `L` / `C` commands), its label's point, and points bounding what it draws. */
+export interface DiagramEdgeShape {
+    d: string;
+    mid: Point;
+    extent: Point[];
+}
+export interface DiagramEdgeShapeOptions {
+    /**
+     * Tree connectors (1.4.15, org charts): an edge drawn as the default bezier runs from its parent's
+     * bottom middle down, across and down into its child's top middle — whatever ports it names.
+     */
+    treeEdges?: boolean;
+}
+/** A port's point on its node's boundary (the node's centre for a missing port). */
+export declare function diagramPortPoint(nodes: readonly DiagramNode[], nodeId: string, portId: string): Point;
+/**
+ * An edge's path, the point its label goes to, and points that bound what it draws (for a fit).
+ * 1.3.17: a bezier leaves and enters along each port's side (down from a bottom port, left into a
+ * left one) — before it always ran horizontally, so edges between top / bottom ports and back
+ * edges looped through the nodes.
+ */
+export declare function diagramEdgeShape(edge: DiagramEdge, nodes: readonly DiagramNode[], options?: DiagramEdgeShapeOptions): DiagramEdgeShape;

package/dist/core/exportEngine.d.ts

@@ -1,8 +1,68 @@
 import { NiceDiagramDocument, DiagramExportOptions } from '../types/diagramTypes';
+import { DiagramPdfOptions } from './pdfWriter';
+/** One thing a scene draws. Paths use only `M`, `L`, `C` and `Z`. */
+export type DiagramSceneItem = {
+    kind: 'path';
+    d: string;
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    dash?: number[];
+} | {
+    kind: 'text';
+    /** The text's anchor point: its middle (or start) at the baseline's height. */
+    x: number;
+    y: number;
+    text: string;
+    size: number;
+    color: string;
+    anchor: 'middle' | 'start';
+};
+/** A diagram as drawing instructions, in its own units, starting at (0, 0). */
+export interface DiagramScene {
+    width: number;
+    height: number;
+    background?: string;
+    items: DiagramSceneItem[];
+}
+export interface DiagramSceneOptions {
+    /** Room around the drawing (40). */
+    padding?: number;
+    /** A background colour (none: transparent). */
+    background?: string;
+    /** Org-chart connectors for edges without their own line type (as the editor draws them). */
+    treeEdges?: boolean;
+}
+/** The drawing of a diagram: its nodes, edges, arrowheads and labels, padded, from (0, 0). */
+export declare function diagramScene(doc: NiceDiagramDocument, options?: DiagramSceneOptions): DiagramScene;
+/** A scene as an SVG document. */
+export declare function sceneToSvg(scene: DiagramScene, scale?: number): string;
 /**
- * Export diagram to SVG string.
+ * Export diagram to SVG string — the same lines and shapes as the canvas (1.4.15; it drew every
+ * edge as a centre-to-centre line).
  */
-export declare function exportToSvg(doc: NiceDiagramDocument, options?: Partial<DiagramExportOptions>): string;
+export declare function exportToSvg(doc: NiceDiagramDocument, options?: Partial<DiagramExportOptions> & {
+    treeEdges?: boolean;
+}): string;
+/** Export a diagram as a PNG image (1.4.15; in a browser — the SVG drawn to a canvas). */
+export declare function exportToPng(doc: NiceDiagramDocument, options?: {
+    scale?: number;
+    background?: string;
+    treeEdges?: boolean;
+}): Promise<Blob>;
+export type { DiagramPdfOptions } from './pdfWriter';
+/**
+ * A scene as a vector PDF: its paths and text (Helvetica), on one page or tiled. The writer loads on
+ * first use.
+ */
+export declare function sceneToPdf(scene: DiagramScene, options?: DiagramPdfOptions): Promise<Uint8Array>;
+/**
+ * Export a diagram as a vector PDF (1.4.15, OmniVerk wishlist #5): the same drawing as the SVG
+ * export — paths and Helvetica text, so it stays sharp at any zoom and its text can be selected —
+ * fitted on one page or tiled over several. Latin text (Polish and other European letters
+ * included) is text; a label in another script is drawn as an image in a browser.
+ */
+export declare function exportToPdf(doc: NiceDiagramDocument, options?: DiagramPdfOptions): Promise<Blob>;
 /**
  * Export diagram to Mermaid syntax string.
  */

package/dist/core/pdfWriter.d.ts

@@ -0,0 +1,19 @@
+import { DiagramScene } from './exportEngine';
+/** A path's commands as [command, numbers][] (M, L, C, Z) — exportEngine's parser, passed in. */
+export type DiagramPathCommands = (d: string) => Array<[string, number[]]>;
+export interface DiagramPdfOptions {
+    /** Paper (default A4). */
+    pageSize?: 'A4' | 'A3' | 'Letter';
+    /** `auto` (default) turns the page to the diagram's longer side. */
+    orientation?: 'auto' | 'portrait' | 'landscape';
+    /** The whole diagram fitted on one page (default), or at full size over as many pages as it takes. */
+    layout?: 'fit' | 'tiles';
+    /** Page margin in points (28). */
+    margin?: number;
+    background?: string;
+    treeEdges?: boolean;
+    /** PDF title. */
+    title?: string;
+}
+/** A diagram as a vector PDF: its paths and text (Helvetica), on one page or tiled. */
+export declare function writeDiagramPdf(scene: DiagramScene, options: DiagramPdfOptions, pathCommands: DiagramPathCommands): Uint8Array;