@vamos-ui/react 0.0.0-stage → 0.3.0

package/dist/components/hierarchy-chart.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Hierarchy chart: a pannable, zoomable tidy-tree diagram (org chart, partner network, site
+ * structure). Collapsible subtrees, search highlight, focus-to-node, drag-to-reparent with a
+ * "Change parent…" alternative, viewport culling for large trees, SVG / PNG export and a list
+ * view. The accessible model is the Tree view pattern, shared by both views.
+ */
+import * as React from "react";
+export declare const hierarchyChartLabels: {
+    canvas: string;
+    instructions: string;
+    zoomIn: string;
+    zoomOut: string;
+    fit: string;
+    zoomLevel: string;
+    expandAll: string;
+    collapseAll: string;
+    vertical: string;
+    horizontal: string;
+    nodeMenu: string;
+    expand: string;
+    collapse: string;
+    center: string;
+    changeParent: string;
+    changeParentTitle: string;
+    changeParentDescription: string;
+    searchNodes: string;
+    noMatches: string;
+    hiddenCount: string;
+    reparented: string;
+    reparentFailed: string;
+    cycle: string;
+    retry: string;
+    loading: string;
+    empty: string;
+};
+export type HierarchyChartLabels = typeof hierarchyChartLabels;
+export interface HierarchyNodeData {
+    id: string;
+    /** `null` for a root. Several roots are allowed. */
+    parentId: string | null;
+}
+export interface HierarchyNodeState {
+    /** 0 = root. */
+    depth: number;
+    childCount: number;
+    descendantCount: number;
+    collapsed: boolean;
+    selected: boolean;
+    /** Matches `highlight`. */
+    matched: boolean;
+    orientation: "vertical" | "horizontal";
+}
+export interface HierarchyReparentEvent {
+    id: string;
+    newParentId: string;
+    oldParentId: string | null;
+}
+export interface HierarchyChartHandle {
+    fit(): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    /** Expands its ancestors, then pans and zooms to the node. */
+    focusNode(id: string): void;
+    expandAll(): void;
+    collapseAll(): void;
+    /** Standalone SVG of the visible (expanded) chart, colours resolved from the current theme. */
+    toSVG(): string;
+    /** PNG of `toSVG()` at `scale` (default 2). */
+    toPNG(scale?: number): Promise<Blob>;
+}
+type NodeSize = {
+    width: number;
+    height: number;
+};
+export interface HierarchyChartProps<T extends HierarchyNodeData> {
+    nodes: readonly T[];
+    /** Node content inside the kit's card frame. Default: `HierarchyNodeCard` with the label. */
+    renderNode?: (node: T, state: HierarchyNodeState) => React.ReactNode;
+    /** Text of a node: search, type-ahead, export, list view. Default `name` / `label` / `title`. */
+    getLabel?: (node: T) => string;
+    /** Second line in export and list view (job title, tier). */
+    getDescription?: (node: T) => string | undefined;
+    /** Vacant / placeholder nodes get a dashed frame. */
+    isPlaceholder?: (node: T) => boolean;
+    orientation?: "vertical" | "horizontal";
+    defaultOrientation?: "vertical" | "horizontal";
+    onOrientationChange?: (o: "vertical" | "horizontal") => void;
+    /** px, or a preset. Default `"card"` (236 × 84). */
+    nodeSize?: NodeSize | "compact" | "card";
+    /** Space between siblings (x) and levels (y). Default `{ x: 28, y: 56 }`. */
+    gap?: {
+        x: number;
+        y: number;
+    };
+    collapsed?: string[];
+    /** Ids, or `{ depth }` to collapse every node at that depth and below. Default: `{ depth: 2 }` beyond 500 nodes. */
+    defaultCollapsed?: string[] | {
+        depth: number;
+    };
+    onCollapsedChange?: (ids: string[]) => void;
+    selected?: string | null;
+    defaultSelected?: string | null;
+    onSelectedChange?: (id: string | null) => void;
+    /** Pans and zooms to this node whenever it changes (search result, deep link). */
+    focusId?: string | null;
+    /** Highlights matching nodes (locale-folded) and opens their ancestors. */
+    highlight?: string;
+    /** Enables drag-to-reparent and "Change parent…". A returned promise keeps the move optimistic. */
+    onReparent?: (event: HierarchyReparentEvent) => void | Promise<void>;
+    /** `true`, or why the move is not allowed. Cycles are always blocked. */
+    canReparent?: (event: HierarchyReparentEvent) => true | string;
+    /** Extra items in each node's action menu. */
+    nodeMenu?: (node: T) => React.ReactNode;
+    view?: "chart" | "list";
+    /** Floating zoom / fit / orientation controls. Default `true`. */
+    controls?: boolean;
+    /** Canvas height. Default `32rem`. */
+    height?: number | string;
+    loading?: boolean;
+    empty?: React.ReactNode;
+    labels?: Partial<HierarchyChartLabels>;
+    "aria-label"?: string;
+    className?: string;
+}
+interface LaidOut<T> {
+    id: string;
+    data: T;
+    depth: number;
+    x: number;
+    y: number;
+    parentId: string | null;
+    childCount: number;
+    posinset: number;
+    setsize: number;
+}
+/**
+ * Tidy-tree layout of a flat `{ id, parentId }` list. Returns top-left node boxes in content
+ * coordinates (origin at 0,0) and the content size. Collapsed nodes hide their subtree.
+ */
+export declare function layoutHierarchy<T extends HierarchyNodeData>(nodes: readonly T[], opts?: {
+    collapsed?: ReadonlySet<string>;
+    orientation?: "vertical" | "horizontal";
+    size?: NodeSize;
+    gap?: {
+        x: number;
+        y: number;
+    };
+    dir?: "ltr" | "rtl";
+}): {
+    nodes: LaidOut<T>[];
+    width: number;
+    height: number;
+};
+/**
+ * ```tsx
+ * <HierarchyChart
+ *   aria-label="Organization"
+ *   nodes={people}
+ *   renderNode={(p) => <HierarchyPersonNode name={p.name} title={p.title} src={p.photo} />}
+ * />
+ * ```
+ */
+export declare const HierarchyChart: <T extends HierarchyNodeData>(props: HierarchyChartProps<T> & {
+    ref?: React.Ref<HierarchyChartHandle>;
+}) => React.ReactElement;
+export interface HierarchyNodeCardProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+    title: React.ReactNode;
+    subtitle?: React.ReactNode;
+    /** Leading visual (icon, logo). */
+    icon?: React.ReactNode;
+    /** Trailing badge (tier, volume). */
+    badge?: React.ReactNode;
+    /** Bottom line (location, count). */
+    meta?: React.ReactNode;
+}
+/** Generic node content: icon · title · subtitle · badge. */
+export declare function HierarchyNodeCard({ title, subtitle, icon, badge, meta, className, ...props }: HierarchyNodeCardProps): React.JSX.Element;
+export interface HierarchyPersonNodeProps extends React.HTMLAttributes<HTMLDivElement> {
+    name: string;
+    title?: string;
+    src?: string | null;
+    /** Bottom line: department, location, team size. */
+    meta?: React.ReactNode;
+    badge?: React.ReactNode;
+    /** An open position: initials replaced by a dashed avatar, name muted. */
+    vacant?: boolean;
+}
+/** Person node for org charts: Avatar · name · job title · meta. */
+export declare function HierarchyPersonNode({ name, title, src, meta, badge, vacant, className, ...props }: HierarchyPersonNodeProps): React.JSX.Element;
+export {};