@x12i/diagrams 1.0.0 → 1.1.0

package/dist/react.d.ts

@@ -0,0 +1,348 @@
+import * as react from 'react';
+import { ReactNode, ComponentPropsWithoutRef, Ref, ComponentPropsWithRef, RefObject, CSSProperties } from 'react';
+import { p as DiagramMessages, q as DiagramMessagesOverride } from './messages-ZCyCfyO0.js';
+import { NodeKind, DiagramNode, LayoutDirection, DiagramDocument, HistoryOptions, DiagramConnection, ConnectionRules, LayoutOptions, EdgeKind, NewNode, Alignment, SvgOptions, DiagramPalette } from './index.js';
+export { Z as Message, _ as MessageValues, az as defaultMessages, aK as exportDiagramJson, aL as exportDiagramSvg } from './messages-ZCyCfyO0.js';
+
+/** The drag-and-drop type used when a palette entry is dragged onto the canvas. */
+declare const PALETTE_DRAG_TYPE = "application/x-kit-diagram-node";
+interface ToolbarSections {
+    /** The "add node" button and the palette it opens. Editable canvases only. */
+    palette?: boolean;
+    /** Undo and redo. */
+    history?: boolean;
+    /** Delete, duplicate, group and ungroup. Editable canvases only. */
+    edit?: boolean;
+    /** Arrange automatically. Editable canvases only. */
+    layout?: boolean;
+    /** Zoom, fit, minimap and grid. */
+    view?: boolean;
+}
+
+/** Why the document changed. Useful for analytics, autosave rules and undo labels. */
+type DiagramChangeReason = "move" | "resize" | "rename" | "rename-edge" | "add-node" | "delete" | "connect" | "disconnect" | "paste" | "duplicate" | "group" | "ungroup" | "collapse" | "layout" | "align" | "distribute" | "update" | "history";
+interface DiagramChange {
+    reason: DiagramChangeReason;
+    /** Nodes the change touched, when that is known. */
+    nodeIds?: string[];
+    /** Edges the change touched, when that is known. */
+    edgeIds?: string[];
+    /** Changes with the same key in a row share one undo step. `useDiagramHistory` honors it. */
+    coalesceKey?: string;
+}
+interface DiagramSelection {
+    nodeIds: string[];
+    edgeIds: string[];
+}
+/** What a custom node body receives. Handles, focus, labels for assistive technology and resizing stay with the canvas. */
+interface DiagramNodeRenderProps {
+    node: DiagramNode;
+    selected: boolean;
+    editing: boolean;
+    rtl: boolean;
+    direction: LayoutDirection;
+    messages: DiagramMessages;
+    /** The label: plain text, or the inline editor while the node is being renamed. Put it somewhere in your body. */
+    label: ReactNode;
+    /** The built-in body for this kind, so a renderer can wrap or extend it. */
+    defaultBody: ReactNode;
+}
+/** Replace the body of a node kind. Return `undefined` to keep the built-in body. */
+type NodeRenderers = Partial<Record<NodeKind, (props: DiagramNodeRenderProps) => ReactNode | undefined>>;
+
+type UseDiagramHistoryOptions = HistoryOptions;
+/** How a change should be recorded. Changes that share a `coalesceKey` in a row become one undo step. */
+interface HistoryChangeMeta {
+    coalesceKey?: string;
+}
+interface DiagramHistory {
+    /** The current document. Pass it to `DiagramCanvas` as `value`. */
+    document: DiagramDocument;
+    /** Records a new document. Pass it to `DiagramCanvas` as `onChange`. */
+    set: (next: DiagramDocument | ((current: DiagramDocument) => DiagramDocument), meta?: HistoryChangeMeta) => void;
+    undo: () => void;
+    redo: () => void;
+    canUndo: boolean;
+    canRedo: boolean;
+    /** Replaces the document and forgets the history, for example after loading a file. */
+    reset: (next: DiagramDocument) => void;
+    /** Forgets the history and keeps the current document. */
+    clear: () => void;
+    /** The number of steps that can be undone. */
+    undoDepth: number;
+    /** The number of steps that can be redone. */
+    redoDepth: number;
+}
+/**
+ * Undo and redo for a diagram. Wire it to the canvas:
+ *
+ * ```tsx
+ * const history = useDiagramHistory(initialDocument);
+ * <DiagramCanvas value={history.document} onChange={history.set} history={history} />
+ * ```
+ *
+ * Without it, an uncontrolled `DiagramCanvas` keeps its own history.
+ */
+declare function useDiagramHistory(initial: DiagramDocument | (() => DiagramDocument), options?: UseDiagramHistoryOptions): DiagramHistory;
+
+/**
+ * An extra rule for new connections, checked after the built-in ones. Return
+ * `true` to allow, `false` to refuse with a generic message, or a string to
+ * refuse and show that (translated) text.
+ */
+type ConnectionValidator = (connection: DiagramConnection, document: DiagramDocument) => boolean | string;
+/** Methods you can call on a canvas through its `ref`. */
+interface DiagramCanvasHandle {
+    fitView: () => void;
+    zoomIn: () => void;
+    zoomOut: () => void;
+    /** Moves keyboard focus to a node, expanding collapsed groups around it first. Returns false for an unknown id. */
+    focusNode: (id: string) => boolean;
+    /** Replaces the selection. */
+    select: (nodeIds: readonly string[], edgeIds?: readonly string[]) => void;
+    clearSelection: () => void;
+    undo: () => void;
+    redo: () => void;
+    /** Arranges the diagram. Options are merged over the canvas `direction` and `layoutOptions`. */
+    applyLayout: (options?: LayoutOptions) => void;
+    /** Adds a node in the middle of the view and returns its id. Does nothing on a read-only canvas. */
+    addNode: (kind: NodeKind, init?: Partial<NewNode>) => string | undefined;
+    align: (alignment: Alignment) => void;
+    distribute: (axis: "horizontal" | "vertical") => void;
+    group: () => void;
+    ungroup: () => void;
+    duplicate: () => void;
+    deleteSelection: () => void;
+    copy: () => void;
+    paste: () => void;
+    getDocument: () => DiagramDocument;
+    getSelection: () => DiagramSelection;
+}
+interface DiagramCanvasProps extends Omit<ComponentPropsWithoutRef<"div">, "onChange" | "defaultValue" | "children" | "dir" | "title"> {
+    /** The diagram, when you own the state. Pair it with `onChange`. */
+    value?: DiagramDocument;
+    /** The starting diagram, when the canvas owns the state. */
+    defaultValue?: DiagramDocument;
+    /** Called with the whole next document and why it changed. */
+    onChange?: (next: DiagramDocument, change: DiagramChange) => void;
+    /** Shows the diagram without editing tools. Selection, navigation, zoom and collapsing still work. */
+    readOnly?: boolean;
+    /** The accessible name of the canvas. Defaults to the translated "Diagram: {title}". */
+    label?: string;
+    /** Direction of the flow. Decides where connection points sit and the Tab order. Defaults to `TB`. */
+    direction?: LayoutDirection;
+    /** Text direction. Defaults to the direction of the surrounding page. */
+    dir?: "ltr" | "rtl";
+    messages?: DiagramMessagesOverride;
+    /** Height of the canvas. Defaults to a comfortable height from the size tokens. */
+    height?: number | string;
+    /** `true` (default) shows every section, `false` none, or choose sections. Editing sections only show when editable. */
+    toolbar?: boolean | ToolbarSections;
+    /** The node types the palette offers. Defaults to all of them. */
+    palette?: readonly NodeKind[];
+    /** Start with the minimap shown. The toolbar toggles it. */
+    minimap?: boolean;
+    /** Start with the dotted grid shown (default true). The toolbar toggles it. */
+    grid?: boolean;
+    /** Snap dragged nodes to the grid. `true` uses the kit grid (8), or give a size. Defaults to true. */
+    snapToGrid?: boolean | number;
+    /** Rules for new connections. Defaults follow `document.kind` (a `dag` refuses cycles, a `tree` also refuses second parents). */
+    connectionRules?: ConnectionRules;
+    /** An extra check for new connections. */
+    validateConnection?: ConnectionValidator;
+    /** Replace the body of a node kind. */
+    nodeRenderers?: NodeRenderers;
+    /** A `useDiagramHistory` result (or anything shaped like it) to drive undo and redo when you own the state. */
+    history?: Pick<DiagramHistory, "undo" | "redo" | "canUndo" | "canRedo">;
+    /** Options for the auto-layout button and `applyLayout`. */
+    layoutOptions?: LayoutOptions;
+    onSelectionChange?: (selection: DiagramSelection) => void;
+    /**
+     * Called when a node is activated: double-click or Enter on a read-only
+     * canvas, and Ctrl or Cmd with Enter on an editable one (plain Enter renames).
+     */
+    onNodeActivate?: (node: DiagramNode) => void;
+    /**
+     * The text outline. `hidden` (default) is reachable by keyboard and screen
+     * reader and appears when it has focus, `visible` always shows it, `false`
+     * leaves it out (render `DiagramOutline` yourself).
+     */
+    outline?: "hidden" | "visible" | false;
+    /** Make connections focusable and deletable from the keyboard. Defaults to false: the outline lists them. */
+    edgesFocusable?: boolean;
+    /** Render only the nodes in view. Faster for very large diagrams, but off-screen nodes are not in the page for assistive technology. */
+    virtualize?: boolean;
+    /** Show the React Flow credit link. Defaults to false; see the README. */
+    showAttribution?: boolean;
+    /** Line style for edges that do not set one. */
+    edgeKind?: EdgeKind;
+    minZoom?: number;
+    maxZoom?: number;
+    /** Zoom with the mouse wheel (default true). Turn it off so the page can scroll over the canvas; Ctrl or Cmd with the wheel still zooms. */
+    wheelZoom?: boolean;
+    /** Fit the diagram to the view when it first appears. Defaults to true. */
+    fitOnMount?: boolean;
+    /** A handle for the methods in `DiagramCanvasHandle`. */
+    ref?: Ref<DiagramCanvasHandle>;
+}
+/**
+ * An accessible, editable node-and-edge diagram. It is controlled
+ * (`value` + `onChange`) or uncontrolled (`defaultValue`), and it is a
+ * read-only viewer with `readOnly`.
+ *
+ * Keyboard: Tab visits nodes in reading order; arrow keys jump to the nearest
+ * node in that direction; Space selects; Enter renames; Delete removes; C
+ * connects; Shift with an arrow nudges. A text outline of the whole diagram
+ * is part of the canvas.
+ */
+declare function DiagramCanvas(props: DiagramCanvasProps): react.JSX.Element;
+
+/**
+ * Moves keyboard focus to a node of a rendered `DiagramCanvas`, found by the
+ * `id` you gave the canvas. Returns false when the node is not on the page
+ * (for example it is inside a collapsed group).
+ */
+declare function focusDiagramNode(canvasId: string, nodeId: string): boolean;
+interface DiagramOutlineProps extends Omit<ComponentPropsWithRef<"section">, "children" | "title"> {
+    document: DiagramDocument;
+    messages?: DiagramMessagesOverride;
+    /** Orders items the way the canvas orders Tab stops. Defaults to `TB`. */
+    direction?: LayoutDirection;
+    /** Right-to-left reading order and text direction. */
+    rtl?: boolean;
+    /** The `id` of a `DiagramCanvas`: choosing a node moves focus to it there. */
+    canvasId?: string;
+    /** A canvas handle (`ref`) to focus nodes through. It can also expand a collapsed group first. */
+    canvas?: RefObject<DiagramCanvasHandle | null>;
+    /** Called when a node is chosen, in addition to the two options above. */
+    onNavigate?: (nodeId: string) => void;
+    /** Adds a button after each connection that removes it. Pass it only for editable diagrams. */
+    onDisconnect?: (edgeId: string) => void;
+    /** The heading level of the title. Defaults to 3. */
+    headingLevel?: 2 | 3 | 4 | 5 | 6;
+    /**
+     * `always` (default) shows the outline. `focus` hides it visually until
+     * keyboard focus is inside it, so it adds no clutter but stays reachable.
+     */
+    reveal?: "always" | "focus";
+    /** Also list the paths through the diagram ("Start to Review to Done"). Defaults to true. */
+    showPaths?: boolean;
+}
+/**
+ * The text twin of a diagram: every node once, grouped like the canvas, with
+ * what each connects to and from, and a link that moves focus to the node.
+ * It is what a screen reader user, a search engine and a printout see.
+ */
+declare function DiagramOutline({ document: doc, messages: messagesOverride, direction, rtl, canvasId, canvas, onNavigate, onDisconnect, headingLevel, reveal, showPaths, className, ...props }: DiagramOutlineProps): react.JSX.Element;
+
+/** The part of Mermaid this component uses. The `mermaid` package satisfies it. */
+interface MermaidApi {
+    initialize: (config: Record<string, unknown>) => void;
+    render: (id: string, text: string) => Promise<{
+        svg: string;
+    }>;
+}
+/**
+ * Loads Mermaid. The package is not a dependency of `@x12i/diagrams`; install
+ * it yourself and pass `() => import("mermaid")`. A module with a `default`
+ * export is accepted too.
+ */
+type MermaidLoader = () => Promise<MermaidApi | {
+    default: MermaidApi;
+}>;
+/**
+ * Mermaid cannot use `var(--token)` (it computes with the colors), so this
+ * reads the current values from the page and returns Mermaid `themeVariables`
+ * that follow the kit theme. Call it again after the theme changes.
+ */
+declare function readKitThemeVariables(element?: Element): Record<string, string>;
+interface MermaidDiagramProps extends Omit<ComponentPropsWithRef<"figure">, "children" | "title" | "onError"> {
+    /** The Mermaid text, for example `graph TD; A-->B;`. */
+    source: string;
+    /** How to get Mermaid. Required, so the app decides when and whether to download it. */
+    loadMermaid: MermaidLoader;
+    /** Accessible name. Defaults to nothing: pass one so the picture has a name. */
+    title: string;
+    /** What the diagram says in words. Strongly recommended: Mermaid output has no text alternative of its own. */
+    description?: string;
+    messages?: DiagramMessagesOverride;
+    /**
+     * Extra Mermaid configuration. `securityLevel` is always `strict` and
+     * `startOnLoad` is always off; they cannot be overridden. `theme` defaults to
+     * `base` with variables from the kit tokens.
+     */
+    config?: Record<string, unknown>;
+    /** Called with the finished, sanitized SVG element. */
+    onRender?: (svg: SVGSVGElement) => void;
+    /** Called when Mermaid cannot be loaded or the source cannot be rendered. */
+    onError?: (error: unknown, kind: "load" | "render") => void;
+    /** Show the source toggle. Defaults to true: the source is the text alternative. */
+    showSourceToggle?: boolean;
+}
+/**
+ * Renders Mermaid text as a themed, sanitized SVG, with a loading state, an
+ * error state that shows the source, and a text alternative. Mermaid is loaded
+ * on demand through `loadMermaid`, so it stays out of your bundle until used.
+ */
+declare function MermaidDiagram({ source, loadMermaid, title, description, messages: messagesOverride, config, onRender, onError, showSourceToggle, className, ...props }: MermaidDiagramProps): react.JSX.Element;
+
+/**
+ * Parses SVG markup (Mermaid's output) into a clean element that is safe to
+ * insert, or returns `null` when there is no SVG in it. It is a second line of
+ * defense: Mermaid is also run with `securityLevel: "strict"`.
+ *
+ * Removed: scripts, frames, objects, embeds, animation elements, every `on*`
+ * attribute, every `href` that is not a `#fragment` (or a safe raster image),
+ * CSS `@import` and any `url()` that leaves the document. The markup is parsed
+ * with `DOMParser` and inserted by the caller with `importNode`, never with
+ * `innerHTML`.
+ */
+declare function sanitizeSvgMarkup(markup: string): SVGSVGElement | null;
+
+interface StaticDiagramProps extends Omit<SvgOptions, "standalone" | "idPrefix"> {
+    /** The diagram to draw. */
+    document: DiagramDocument;
+    /** Translations. Only the word that joins labels in the description ("A to B") is used here. */
+    messages?: DiagramMessagesOverride;
+    /** Unique id prefix for the SVG's internal ids. Defaults to a generated one. */
+    idPrefix?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * A diagram as plain, non-interactive SVG. It renders the same picture as
+ * `diagramToSvg`, but as React elements: no markup is injected, no editor code
+ * runs, and it works in server components. Colors follow the page theme
+ * through the kit tokens. The SVG has a title, a description (the text outline
+ * by default) and `role="img"`.
+ *
+ * Use it for reports, documentation and anywhere the reader should not edit.
+ */
+declare function StaticDiagram({ document: doc, messages, idPrefix, className, style, ...options }: StaticDiagramProps): ReactNode;
+
+/**
+ * Saves a file from the browser. Pass a string (with a `type`) or a `Blob`.
+ * Browser only: call it from an event handler.
+ */
+declare function downloadBlob(content: Blob | string, filename: string, type?: string): void;
+/**
+ * Replaces every `var(--kit-...)` in a string with the value it has on
+ * `element` (the page root by default). Unknown variables use their fallback
+ * or are left as written. Use it before saving an SVG that will be opened
+ * outside a themed page.
+ */
+declare function resolveCssVariables(text: string, element?: Element): string;
+/** The palette the static SVG uses, with every token resolved to its current value. */
+declare function readDiagramPalette(element?: Element): DiagramPalette;
+interface DownloadSvgOptions extends SvgOptions {
+    filename?: string;
+    /** Where to read token values from. Defaults to the page root. */
+    element?: Element;
+}
+/** Saves the diagram as a stand-alone `.svg` file, with the current theme's colors baked in. */
+declare function downloadDiagramSvg(doc: DiagramDocument, options?: DownloadSvgOptions): void;
+/** Saves the diagram document as a `.json` file. Import it again with `importDiagram`. */
+declare function downloadDiagramJson(doc: DiagramDocument, filename?: string): void;
+
+export { DiagramCanvas, DiagramMessages, DiagramMessagesOverride, DiagramOutline, MermaidDiagram, PALETTE_DRAG_TYPE, StaticDiagram, downloadBlob, downloadDiagramJson, downloadDiagramSvg, focusDiagramNode, readDiagramPalette, readKitThemeVariables, resolveCssVariables, sanitizeSvgMarkup, useDiagramHistory };
+export type { ConnectionValidator, DiagramCanvasHandle, DiagramCanvasProps, DiagramChange, DiagramChangeReason, DiagramHistory, DiagramNodeRenderProps, DiagramOutlineProps, DiagramSelection, DownloadSvgOptions, HistoryChangeMeta, MermaidApi, MermaidDiagramProps, MermaidLoader, NodeRenderers, StaticDiagramProps, ToolbarSections, UseDiagramHistoryOptions };