@nice2dev/ui-diagrams 1.3.16 → 1.3.17

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @nice2dev/ui-diagrams — Changelog
 
+## 1.3.17
+
+### Patch Changes
+
+- 8ae6e97: NiceWorkflowDesigner moves to `@nice2dev/ui-diagrams` (showcase feedback round 41):
+
+  - **Moved** (breaking for imports): `import { NiceWorkflowDesigner } from '@nice2dev/ui-diagrams'`. The data types
+    (`NiceWorkflowDefinition`, `NiceWorkflowState`, `NiceWorkflowTransition`…) stay in `@nice2dev/ui`;
+    `NiceWorkflowState.type` also takes ids of your own step kinds.
+  - Rebuilt on the diagram canvas: **arrows** between the steps, **automatic layered layout** (left to right, or
+    `layoutDirection="TB"`), the whole flow **fitted to the canvas at start**, zoom − / % / + and Fit in the toolbar,
+    wheel zoom, pan by dragging the empty canvas.
+  - **Step kinds**: `stepTypes` (default start, state, approval, end, error) and `loadStepTypes` (loaded at mount,
+    merged by id); "Add step" offers them all.
+  - A new step gets a **unique name** and comes **connected from the selected step** (the duplicated "New state"
+    dead-end / orphan pair is gone); transitions are drawn from a step's port onto another step or edited in the
+    properties panel (name, target, add, delete); a selected transition has its own panel; a problem message selects
+    its step.
+  - The designer keeps the workflow itself; `onChange` reports every change with the laid-out positions.
+
+  NiceDiagramEditor, more configurable (backward compatible): `document` (controlled), `nodeTypes` (a palette),
+  `autoLayout`, `fitOnMount`, `readOnly`; connections drawn from the ports (`onEdgeCreate` was declared but never
+  called); `onChange` fires for every change (only undo / redo reached it — the editor hook memoised on a document the
+  model edits in place, which also froze the viewport and the undo state) and no longer during render; `lang` follows
+  the app's language by default. DiagramCanvas: `autoFit` / `fitKey` / `refitKey`, `resizable`, `panOnDrag`,
+  `onResize`, `ariaLabel`, per-instance arrow markers, curves that leave and enter along their ports' sides, labels on
+  the curve's middle. The `dagre` layout is a real layered layout now (cycle breaking, longest-path ranks, barycenter
+  ordering, top-left positions, `ranks` in the result); `fitViewport` / `diagramBounds` exported; a layout is one undo
+  step.
+
+  ui-forms: the studio's workflow screen uses the designer from `@nice2dev/ui-diagrams` (new peer dependency).
+
 ## 1.3.16
 
 No changes in this release.

package/dist/components/DiagramCanvas.d.ts

@@ -20,8 +20,32 @@ export interface DiagramCanvasProps {
     onNodeDragEnd?: (nodeId: string, position: Point) => void;
     /** Node resize (editor only) */
     onNodeResize?: (nodeId: string, size: Size, position: Point) => void;
-    /** Edge creation (editor only) */
-    onEdgeCreate?: (sourceNodeId: string, targetNodeId: string) => void;
+    /**
+     * Edge creation (editor only): a drag from a node's port dropped on another node. With it the
+     * ports start connections; the ports are the ones dragged from and nearest to the drop.
+     */
+    onEdgeCreate?: (sourceNodeId: string, targetNodeId: string, sourcePortId?: string, targetPortId?: string) => void;
+    /**
+     * Fit the whole diagram in view (1.3.17): at mount, when the canvas resizes and when `fitKey`
+     * changes — until the user zooms or pans; a new `fitKey` after that waits for `refitKey`.
+     */
+    autoFit?: boolean;
+    /** Change it to fit again, e.g. after an automatic layout. */
+    fitKey?: string | number;
+    /** Change it to fit now, also after the user zoomed or panned (a "Fit" button). */
+    refitKey?: string | number;
+    /** Margin of the fit in screen pixels (default 40). */
+    fitPadding?: number;
+    /** Largest zoom of the fit (default 1.25). */
+    fitMaxZoom?: number;
+    /** Called with the canvas size in pixels whenever it changes. */
+    onResize?: (size: Size) => void;
+    /** Show resize handles on the selected node (default true). */
+    resizable?: boolean;
+    /** A left drag on the empty canvas pans it, instead of a selection rectangle (default false). */
+    panOnDrag?: boolean;
+    /** The canvas's accessible name. */
+    ariaLabel?: string;
     /** In-place text editing */
     onNodeLabelChange?: (nodeId: string, label: string) => void;
     /** Animation states (viewer only) */

package/dist/components/NiceDiagramEditor.d.ts

@@ -1,17 +1,42 @@
 import { NiceComponentTutorial } from '@nice2dev/ui';
 import { default as React } from 'react';
-import { NiceDiagramDocument, DiagramType } from '../types/diagramTypes';
+import { NiceDiagramDocument, NiceDiagramNodeType, DiagramType, LayoutOptions } from '../types/diagramTypes';
 export interface NiceDiagramEditorProps {
     /** Initial document (optional — empty diagram created if omitted) */
     initialDocument?: NiceDiagramDocument;
+    /**
+     * The document, controlled (1.3.17): a new one replaces what the editor shows. Every change
+     * still comes through `onChange` — pass back what it gives.
+     */
+    document?: NiceDiagramDocument;
+    /**
+     * The kinds of node to offer (1.3.17): a palette above the canvas, each entry adding a node with
+     * its label, shape, size, style, icon and ports (and `data.nodeType`).
+     */
+    nodeTypes?: NiceDiagramNodeType[];
+    /**
+     * Lay the nodes out after every structural change — a node or an edge added or removed
+     * (1.3.17). Dragging nodes is off then. `true`: layered, left to right.
+     */
+    autoLayout?: boolean | LayoutOptions;
+    /**
+     * Fit the whole diagram in view at mount, on resize and after each automatic layout, until the
+     * user zooms or pans (1.3.17). The toolbar's reset-zoom button fits again.
+     */
+    fitOnMount?: boolean;
+    /** View only (1.3.17): no toolbar, property panel, dragging or connecting. */
+    readOnly?: boolean;
     /** Diagram type when creating empty (default: flowchart) */
     diagramType?: DiagramType;
     /** Fires on every document change */
     onChange?: (doc: Readonly<NiceDiagramDocument>) => void;
     /** Export callback (called when user exports via toolbar) */
     onExport?: (format: string, content: string) => void;
-    /** Language (default: en) */
-    lang?: 'en' | 'pl';
+    /**
+     * 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.
+     */
+    lang?: string;
     /** Show/hide panels */
     showToolbar?: boolean;
     showPropertyPanel?: boolean;

package/dist/components/NiceWorkflowDesigner.d.ts

@@ -0,0 +1,72 @@
+import { NiceBaseProps, NiceComponentTutorial, NiceFieldDescriptor, NiceRoleInfo, NiceUserInfo, NiceWorkflowActionType, NiceWorkflowDefinition } from '@nice2dev/ui';
+import { default as React } from 'react';
+import { NodeShape } from '../types/diagramTypes';
+/** What a kind of step means to the validation and the simulation. */
+export type NiceWorkflowStepRole = 'initial' | 'step' | 'final' | 'error';
+/** A kind of step of the {@link NiceWorkflowDesigner} — `state.type` holds its id. */
+export interface NiceWorkflowStepType {
+    id: string;
+    /** The "Add step" entry, the new step's name and the caption under every step's name. */
+    label: string;
+    /** A NiceIcon name. */
+    icon?: string;
+    /** The step's border — any CSS colour, a theme variable best (`var(--nice-color-primary)`). */
+    color?: string;
+    shape?: NodeShape;
+    /**
+     * Default: `initial`, `final` and `error` for the ids of the same name, `step` otherwise. A
+     * workflow needs one initial and at least one final step; final and error steps may end it.
+     */
+    role?: NiceWorkflowStepRole;
+    /** Shown in the "Add step" menu. */
+    description?: string;
+}
+/** Props for {@link NiceWorkflowDesigner}. */
+export interface NiceWorkflowDesignerProps extends NiceBaseProps {
+    workflow?: NiceWorkflowDefinition;
+    /** Convenience: flat node list mapped into `workflow.states` when `workflow` is omitted. */
+    nodes?: Array<{
+        id: string;
+        type?: string;
+        label?: string;
+        name?: string;
+        x?: number;
+        y?: number;
+    }>;
+    /** Convenience: flat edge list mapped into `workflow.transitions` when `workflow` is omitted. */
+    edges?: Array<{
+        id?: string;
+        from?: string;
+        to?: string;
+        source?: string;
+        target?: string;
+        fromStateId?: string;
+        toStateId?: string;
+        name?: string;
+        label?: string;
+    }>;
+    /**
+     * Every change. The designer keeps the workflow itself, so it works without this too; a
+     * `workflow` that differs from the last one it gave out replaces what it shows.
+     */
+    onChange?: (workflow: NiceWorkflowDefinition) => void;
+    entityFields?: NiceFieldDescriptor[];
+    availableActions?: NiceWorkflowActionType[];
+    availableUsers?: NiceUserInfo[];
+    availableRoles?: NiceRoleInfo[];
+    readOnly?: boolean;
+    showMinimap?: boolean;
+    showToolbar?: boolean;
+    showValidation?: boolean;
+    onTest?: (workflow: NiceWorkflowDefinition) => void;
+    onPublish?: (workflow: NiceWorkflowDefinition) => void;
+    /** Optional "?" guided tour. Off by default; `true` uses the built-in tour. */
+    tutorial?: NiceComponentTutorial;
+    /** The kinds of step (default: start, state, approval, end, error). */
+    stepTypes?: NiceWorkflowStepType[];
+    /** More kinds of step, loaded once at mount and merged by id over `stepTypes`. */
+    loadStepTypes?: () => Promise<NiceWorkflowStepType[]>;
+    /** Which way the flow runs (default `'LR'`, left to right). */
+    layoutDirection?: 'LR' | 'TB';
+}
+export declare const NiceWorkflowDesigner: React.FC<NiceWorkflowDesignerProps>;

package/dist/core/DiagramModel.d.ts

@@ -24,6 +24,11 @@ export declare class DiagramModel {
     canRedo(): boolean;
     addNode(label: string, position: Point, shape?: NodeShape, size?: Size): DiagramNode;
     updateNode(id: string, patch: Partial<Omit<DiagramNode, 'id'>>): void;
+    /**
+     * Moves several nodes in one go (a layout) — one undo step, or none with `recordHistory: false`
+     * (an automatic layout that follows every change: undoing the change lays it out again).
+     */
+    moveNodes(positions: ReadonlyMap<string, Point>, recordHistory?: boolean): void;
     moveNode(id: string, position: Point): void;
     resizeNode(id: string, size: Size): void;
     removeNode(id: string): void;

package/dist/core/layoutEngine.d.ts

@@ -1,6 +1,9 @@
 import { DiagramNode as _DiagramNode, DiagramEdge as _DiagramEdge, LayoutOptions, Point as _Point } from '../types/diagramTypes';
 export interface LayoutResult {
+    /** Top-left corner of each node. */
     positions: Map<string, _Point>;
+    /** The layered layouts (`dagre`, `tree`): the rank (layer) of each node, 0 first. */
+    ranks?: Map<string, number>;
 }
 /**
  * Apply an auto-layout algorithm and return computed positions.

package/dist/core/viewportFit.d.ts

@@ -0,0 +1,20 @@
+import { DiagramNode, DiagramViewport, Size } from '../types/diagramTypes';
+/** A rectangle in diagram coordinates. */
+export interface DiagramBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** The box around the nodes (hidden ones left out), `null` without any. */
+export declare function diagramBounds(nodes: readonly DiagramNode[]): DiagramBounds | null;
+export interface FitViewportOptions {
+    /** Margin around the content, in screen pixels (default 40). */
+    padding?: number;
+    /** Never zoom in further than this (default 1.25): a small diagram is not blown up. */
+    maxZoom?: number;
+    /** Never zoom out further than this (default 0.1). */
+    minZoom?: number;
+}
+/** The viewport that shows `bounds` whole and centred in a canvas of `size`. */
+export declare function fitViewport(bounds: DiagramBounds | null, size: Size, options?: FitViewportOptions): DiagramViewport;

package/dist/hooks/useDiagramEditor.d.ts

@@ -46,7 +46,10 @@ export interface UseDiagramEditorReturn {
     setViewMode: (mode: DiagramViewMode) => void;
     viewMode: DiagramViewMode;
     /** Layout */
-    applyLayout: (options: LayoutOptions) => void;
+    /** Lays the nodes out — one undo step, or none with '{ history: false }'. */
+    applyLayout: (options: LayoutOptions, opts?: {
+        history?: boolean;
+    }) => void;
     /** Viewport */
     setViewport: (viewport: DiagramViewport) => void;
     /** Undo/redo */
@@ -58,5 +61,10 @@ export interface UseDiagramEditorReturn {
     loadDocument: (doc: NiceDiagramDocument) => void;
     /** Model ref */
     model: DiagramModel;
+    /**
+     * Grows with every change. The model edits its document in place, so the document keeps its
+     * identity: watch this to react to changes (1.3.17).
+     */
+    revision: number;
 }
 export declare function useDiagramEditor(initialDoc?: NiceDiagramDocument): UseDiagramEditorReturn;