@smwb/ui-react 2.8.0 → 2.10.0

package/dist/components/dataDisplay/dagView/dagView.d.ts

@@ -0,0 +1,157 @@
+import React from "react";
+import { type DagDirection, type DagLayoutInput, type DagLayoutResult } from "./dagLayout";
+import { type Viewport } from "./panZoom";
+/** A node's status: a built-in one, coloured by the theme, or any word of the app's, styled by `[data-status]`. */
+export type DagViewStatus = "idle" | "pending" | "running" | "success" | "warning" | "error" | "skipped" | (string & {});
+export interface DagViewNode<T = unknown> {
+    /** Unique among the nodes; edges name nodes by it. */
+    id: string;
+    /** What the default node shows, and its accessible name; the id unless given. */
+    label?: React.ReactNode;
+    /** Colours the node's accent from the theme. */
+    status?: DagViewStatus | undefined;
+    /** The node's accent colour, over its status colour: any CSS colour. */
+    accent?: string | undefined;
+    /** The node's width in pixels; `nodeWidth` unless given. */
+    width?: number | undefined;
+    /** The node's height in pixels; `nodeHeight` unless given. */
+    height?: number | undefined;
+    /** Anything of the app's, handed back to `renderNode` and `onNodeClick`. */
+    data?: T;
+    /** Shown, focusable, but not selectable. */
+    disabled?: boolean | undefined;
+}
+export interface DagViewEdge {
+    /** `source->target` unless given. */
+    id?: string | undefined;
+    /** The id of the node the edge starts from: the one depended on. */
+    source: string;
+    /** The id of the node the edge points to: the one that depends on `source`. */
+    target: string;
+}
+/** A node's state for `renderNode`: a snapshot of the render it is passed to. */
+export interface DagViewNodeState {
+    readonly selected: boolean;
+    /** Next to the selected node: "upstream" feeds it, "downstream" depends on it. */
+    readonly related: "upstream" | "downstream" | null;
+    /** Set apart from the selected node and its neighbours, with `dimUnrelated`. */
+    readonly dimmed: boolean;
+    /** Has keyboard focus. */
+    readonly focused: boolean;
+}
+/** Where the graph is: moved by x, y (pixels) and scaled by zoom. */
+export type DagViewViewport = Viewport;
+/** Moves the view from outside; handed over by `apiRef` once the graph is in the page. */
+export interface DagViewApi {
+    /** Fits the whole graph in view. */
+    fitView(): void;
+    /** Zooms to `zoom` around the middle of the view. */
+    zoomTo(zoom: number): void;
+    /** Zooms by `factor` around the middle of the view. */
+    zoomBy(factor: number): void;
+    /** Moves the node with this id to the middle of the view. */
+    centerNode(id: string): void;
+}
+/** Texts for assistive technology and the zoom buttons, English by default. */
+export interface DagViewLabels {
+    /** What the graph is called as a widget: "dependency graph". */
+    roleDescription: string;
+    /** "Status", before a node's status word. */
+    status: string;
+    /** "Depends on", before the names of the nodes a node's edges come from. */
+    dependsOn: string;
+    /** "Required by", before the names of the nodes a node's edges go to. */
+    requiredBy: string;
+    /** Status words, shown on the default nodes and read out: { running: "Running", … }. */
+    statuses: Record<string, string>;
+    zoomIn: string;
+    zoomOut: string;
+    fitView: string;
+    /** The name of the group of zoom buttons. */
+    controls: string;
+}
+export interface DagViewProps<T = unknown> extends Omit<React.HTMLAttributes<HTMLDivElement>, "onClick"> {
+    /** What the graph shows: its accessible name. */
+    label: string;
+    /** The graph in words, for screen readers; it is there on the server too. */
+    summary?: string | undefined;
+    /** The nodes. A change of status, label or data alone does not lay the graph out again. */
+    nodes: readonly DagViewNode<T>[];
+    /** The edges, from the node depended on to the node that depends on it. */
+    edges: readonly DagViewEdge[];
+    /**
+     * Draws a node's content inside its box; the default shows a status dot,
+     * the label and the status word. `node` and `state` are a snapshot of the
+     * render they are passed to. Keep the content non-interactive where you can:
+     * a node is an ARIA option, whose content assistive technology may read as
+     * plain text, and a click in it also selects the node. Links and buttons in
+     * it are left out of the Tab order except in the node that is the graph's
+     * Tab stop.
+     */
+    renderNode?: ((node: DagViewNode<T>, state: DagViewNodeState) => React.ReactNode) | undefined;
+    /** Which way the layers run: "LR" (left to right, default) or "TB" (top to bottom). */
+    direction?: DagDirection | undefined;
+    /** A node's width in pixels, unless the node sets its own; 180 by default. */
+    nodeWidth?: number | undefined;
+    /** A node's height in pixels, unless the node sets its own; 56 by default. */
+    nodeHeight?: number | undefined;
+    /** The space between layers in pixels; 64 by default. */
+    rankGap?: number | undefined;
+    /** The space between nodes in a layer in pixels; 24 by default. */
+    nodeGap?: number | undefined;
+    /**
+     * Lays the graph out in place of the built-in layout, e.g. with dagre or elk. It must be
+     * synchronous. The layout re-runs when the graph's shape changes; swapping this function
+     * alone does not.
+     */
+    layout?: ((input: DagLayoutInput) => DagLayoutResult) | undefined;
+    /** The selected node's id (controlled); null selects nothing. */
+    selectedId?: string | null | undefined;
+    /** The node selected at first (uncontrolled). */
+    defaultSelectedId?: string | null | undefined;
+    /** A node was selected (its id) or the selection was cleared (null). */
+    onSelectedChange?: ((id: string | null) => void) | undefined;
+    /** A node was clicked, or chosen with Enter or Space. Not called for a disabled node. */
+    onNodeClick?: ((node: DagViewNode<T>, event: React.MouseEvent | React.KeyboardEvent) => void) | undefined;
+    /** Fades the nodes and edges that are not next to the selected node. */
+    dimUnrelated?: boolean | undefined;
+    /** Where the graph is (controlled). */
+    viewport?: DagViewViewport | undefined;
+    /** Where the graph is at first (uncontrolled); with `fit={false}` the page does not move after it loads. */
+    defaultViewport?: DagViewViewport | undefined;
+    /** The view moved or zoomed: at most once per frame during a gesture. */
+    onViewportChange?: ((viewport: DagViewViewport) => void) | undefined;
+    /** Fits the graph in view once it is in the page, and again when its nodes or edges change; true by default. */
+    fit?: boolean | undefined;
+    /** The smallest zoom; 0.1 by default. */
+    minZoom?: number | undefined;
+    /** The largest zoom; 2 by default. */
+    maxZoom?: number | undefined;
+    /** What a plain mouse wheel does: "zoom" (default), "pan", or "none" (the page scrolls). Ctrl+wheel and a trackpad pinch always zoom. */
+    wheel?: "zoom" | "pan" | "none" | undefined;
+    /** Shows the zoom in, zoom out and fit buttons; true by default. */
+    controls?: boolean | undefined;
+    /** Texts for assistive technology and the buttons, over the English defaults. */
+    labels?: Partial<DagViewLabels> | undefined;
+    /**
+     * The graph's height: a number of pixels or any CSS length; 480 by default,
+     * from the stylesheet, so a height in `style` works too. It fills the width.
+     */
+    height?: number | string | undefined;
+    /** Gets the functions that move the view from outside. */
+    apiRef?: ((api: DagViewApi) => void) | undefined;
+    /** Test id of the root `<div>`; `dag-view` unless given. */
+    "data-testid"?: string | undefined;
+}
+/**
+ * A directed graph of dependencies: nodes in layers, left to right or top to
+ * bottom, joined by arrows. A node is selected by a click or the keyboard, and
+ * the edges into and out of it light up; the view pans and zooms with a mouse,
+ * a trackpad, touch or the keyboard.
+ *
+ * `forwardRef` pins the props' generic to its default, so the export is
+ * re-typed over it: `T` is inferred from `nodes`, and `renderNode` and
+ * `onNodeClick` see `node.data` as `T`.
+ */
+export declare const DagView: <T = unknown>(props: DagViewProps<T> & React.RefAttributes<HTMLDivElement>) => React.ReactElement | null;
+export default DagView;