@dynect/base 0.1.0 → 0.2.0

package/src/runtime/components/base/org-chart/svg-icons.ts

@@ -0,0 +1,58 @@
+/**
+ * @description SVG Icon constants for org chart buttons
+ * @author      Amirul Apex
+ * @created     Jan 2026
+ * @project     Dynect
+ */
+
+export const SVG_ICONS = {
+	/**
+	 * Chevron pointing left (collapse indicator for left layout)
+	 */
+	chevronLeft: `<path d="M14.283 3.50094L6.51 11.4749C6.37348 11.615 6.29707 11.8029 6.29707 11.9984C6.29707 12.194 6.37348 12.3819 6.51 12.5219L14.283 20.4989C14.3466 20.5643 14.4226 20.6162 14.5066 20.6516C14.5906 20.6871 14.6808 20.7053 14.772 20.7053C14.8632 20.7053 14.9534 20.6871 15.0374 20.6516C15.1214 20.6162 15.1974 20.5643 15.261 20.4989C15.3918 20.365 15.4651 20.1852 15.4651 19.9979C15.4651 19.8107 15.3918 19.6309 15.261 19.4969L7.9515 11.9984L15.261 4.50144C15.3914 4.36756 15.4643 4.18807 15.4643 4.00119C15.4643 3.81431 15.3914 3.63482 15.261 3.50094C15.1974 3.43563 15.1214 3.38371 15.0374 3.34827C14.9534 3.31282 14.8632 3.29456 14.772 3.29456C14.6808 3.29456 14.5906 3.31282 14.5066 3.34827C14.4226 3.38371 14.3466 3.43563 14.283 3.50094V3.50094Z" fill="#716E7B" stroke="#716E7B"/>`,
+
+	/**
+	 * Chevron pointing right (expand indicator for left layout, collapse for right layout)
+	 */
+	chevronRight: `<path d="M7.989 3.49944C7.85817 3.63339 7.78492 3.8132 7.78492 4.00044C7.78492 4.18768 7.85817 4.36749 7.989 4.50144L15.2985 11.9999L7.989 19.4969C7.85817 19.6309 7.78492 19.8107 7.78492 19.9979C7.78492 20.1852 7.85817 20.365 7.989 20.4989C8.05259 20.5643 8.12863 20.6162 8.21261 20.6516C8.2966 20.6871 8.38684 20.7053 8.478 20.7053C8.56916 20.7053 8.6594 20.6871 8.74338 20.6516C8.82737 20.6162 8.90341 20.5643 8.967 20.4989L16.74 12.5234C16.8765 12.3834 16.9529 12.1955 16.9529 11.9999C16.9529 11.8044 16.8765 11.6165 16.74 11.4764L8.967 3.50094C8.90341 3.43563 8.82737 3.38371 8.74338 3.34827C8.6594 3.31282 8.56916 3.29456 8.478 3.29456C8.38684 3.29456 8.2966 3.31282 8.21261 3.34827C8.12863 3.38371 8.05259 3.43563 7.989 3.50094V3.49944Z" fill="#716E7B" stroke="#716E7B"/>`,
+
+	/**
+	 * Chevron pointing down (collapse indicator for top/bottom layouts)
+	 */
+	chevronDown: `<path d="M19.497 7.98903L12 15.297L4.503 7.98903C4.36905 7.85819 4.18924 7.78495 4.002 7.78495C3.81476 7.78495 3.63495 7.85819 3.501 7.98903C3.43614 8.05257 3.38462 8.12842 3.34944 8.21213C3.31427 8.29584 3.29615 8.38573 3.29615 8.47653C3.29615 8.56733 3.31427 8.65721 3.34944 8.74092C3.38462 8.82463 3.43614 8.90048 3.501 8.96403L11.4765 16.74C11.6166 16.8765 11.8044 16.953 12 16.953C12.1956 16.953 12.3834 16.8765 12.5235 16.74L20.499 8.96553C20.5643 8.90193 20.6162 8.8259 20.6517 8.74191C20.6871 8.65792 20.7054 8.56769 20.7054 8.47653C20.7054 8.38537 20.6871 8.29513 20.6517 8.21114C20.6162 8.12715 20.5643 8.05112 20.499 7.98753C20.3651 7.85669 20.1852 7.78345 19.998 7.78345C19.8108 7.78345 19.6309 7.85669 19.497 7.98753V7.98903Z" fill="#716E7B" stroke="#716E7B"/>`,
+
+	/**
+	 * Chevron pointing up (expand indicator for top/bottom layouts)
+	 */
+	chevronUp: `<path d="M11.457 8.07005L3.49199 16.4296C3.35903 16.569 3.28485 16.7543 3.28485 16.9471C3.28485 17.1398 3.35903 17.3251 3.49199 17.4646L3.50099 17.4736C3.56545 17.5414 3.64304 17.5954 3.72904 17.6324C3.81504 17.6693 3.90765 17.6883 4.00124 17.6883C4.09483 17.6883 4.18745 17.6693 4.27344 17.6324C4.35944 17.5954 4.43703 17.5414 4.50149 17.4736L12.0015 9.60155L19.4985 17.4736C19.563 17.5414 19.6405 17.5954 19.7265 17.6324C19.8125 17.6693 19.9052 17.6883 19.9987 17.6883C20.0923 17.6883 20.1849 17.6693 20.2709 17.6324C20.3569 17.5954 20.4345 17.5414 20.499 17.4736L20.508 17.4646C20.641 17.3251 20.7151 17.1398 20.7151 16.9471C20.7151 16.7543 20.641 16.569 20.508 16.4296L12.543 8.07005C12.4729 7.99653 12.3887 7.93801 12.2954 7.89801C12.202 7.85802 12.1015 7.8374 12 7.8374C11.8984 7.8374 11.798 7.85802 11.7046 7.89801C11.6113 7.93801 11.527 7.99653 11.457 8.07005Z" fill="#716E7B" stroke="#716E7B"/>`,
+} as const;
+
+/**
+ * Creates an SVG icon element with count display
+ * @param iconPath - SVG path data from SVG_ICONS
+ * @param count - Number to display next to the icon
+ * @param marginLeft - Optional left margin for the count (default: 0)
+ * @returns HTML string for the icon with count
+ */
+export function createIconSVG(iconPath: string, count: number, marginLeft: string = '0'): string {
+	return `<div style="display:flex;"><span style="align-items:center;display:flex;"><svg width="8" height="8" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+      ${iconPath}
+      </svg></span><span style="margin-left:${marginLeft};color:#716E7B">${count}</span></div>`;
+}
+
+/**
+ * Gets the appropriate icon for a given layout and state
+ * @param layout - The layout type (left, right, top, bottom)
+ * @param hasChildren - Whether the node has children (collapsed state)
+ * @returns SVG path string
+ */
+export function getLayoutIcon(layout: 'left' | 'right' | 'top' | 'bottom', hasChildren: boolean): string {
+	const iconMap = {
+		left: hasChildren ? SVG_ICONS.chevronLeft : SVG_ICONS.chevronRight,
+		right: hasChildren ? SVG_ICONS.chevronRight : SVG_ICONS.chevronLeft,
+		top: hasChildren ? SVG_ICONS.chevronUp : SVG_ICONS.chevronDown,
+		bottom: hasChildren ? SVG_ICONS.chevronDown : SVG_ICONS.chevronUp,
+	};
+
+	return iconMap[layout];
+}

package/src/runtime/components/base/org-chart/types.ts

@@ -0,0 +1,492 @@
+import type { FlextreeLayout } from 'd3-flextree';
+import type { HierarchyNode, Selection, ZoomBehavior, D3ZoomEvent } from 'd3';
+
+// ============================================================================
+// Core Data Structures
+// ============================================================================
+
+/**
+ * Base data interface for organization chart nodes
+ * Supports flexible id/parentId property naming and custom properties
+ */
+export interface OrgChartNodeData {
+	// ID properties (flexible naming)
+	nodeId?: string | number;
+	id?: string | number;
+	parentNodeId?: string | number;
+	parentId?: string | number;
+
+	// Runtime state flags
+	_expanded?: boolean;
+	_centered?: boolean;
+	_highlighted?: boolean;
+	_upToTheRootHighlighted?: boolean;
+	_pagingButton?: boolean;
+	_pagingStep?: number;
+	_directSubordinates?: number;
+	_totalSubordinates?: number;
+	_directSubordinatesPaging?: number;
+	_filteredOut?: boolean;
+	_centeredWithDescendants?: boolean;
+	_children?: any[];
+
+	// Depth property
+	depth?: number;
+
+	// Allow any custom properties
+	[key: string]: any;
+}
+
+/**
+ * Extended hierarchy node with layout-specific properties
+ */
+/**
+ * Extended hierarchy node with layout-specific properties
+ */
+export interface OrgChartNode<Datum = any> extends HierarchyNode<Datum & OrgChartNodeData> {
+	// Position coordinates
+	x: number;
+	y: number;
+	x0?: number;
+	y0?: number;
+
+	// Dimensions
+	width: number;
+	height: number;
+
+	// Compact layout properties
+	flexCompactDim?: [number, number];
+	firstCompact?: boolean;
+	firstCompactNode?: this;
+	compactEven?: boolean;
+	row?: number;
+
+	// Collapsed children
+	_children?: this[];
+
+	// Paging button visibility
+	_pagingButton?: boolean;
+
+	// Override parent/children types to be OrgChartNode
+	// Using 'this' type to maintain type compatibility with HierarchyNode
+	parent: this | null;
+	children?: this[];
+}
+
+/**
+ * Connection between two nodes (for custom relationships)
+ */
+export interface Connection<Datum = any> {
+	from: string | number;
+	to: string | number;
+	label?: string;
+	_source?: OrgChartNode<Datum>;
+	_target?: OrgChartNode<Datum>;
+}
+
+// ============================================================================
+// Callback & Accessor Types
+// ============================================================================
+
+/**
+ * Generic accessor function for extracting values from nodes
+ */
+/**
+ * Generic accessor function for extracting values from nodes
+ */
+export type NodeAccessor<Result, Datum = any> = (node: OrgChartNode<Datum>) => Result;
+
+/**
+ * Accessor that can work with raw data
+ */
+export type DataAccessor<Result, Datum = any> = (data: Datum) => Result;
+
+/**
+ * Zoom event callbacks
+ */
+export type ZoomCallback<Datum = any> = (event: D3ZoomEvent<SVGSVGElement, Datum>) => void;
+
+/**
+ * Node interaction callbacks
+ */
+export type NodeClickCallback<Datum = any> = (node: OrgChartNode<Datum>) => void;
+export type NodeExpandCollapseCallback<Datum = any> = (node: OrgChartNode<Datum>) => void;
+
+/**
+ * Node content generators (return HTML strings)
+ */
+export type NodeContentCallback<Datum = any> = (node: OrgChartNode<Datum>) => string;
+
+/**
+ * Button content callback with state context
+ */
+export interface ButtonContentArgs<Datum = any> {
+	node: OrgChartNode<Datum>;
+	state: OrgChartAttrs<Datum>;
+}
+export type ButtonContentCallback<Datum = any> = (args: ButtonContentArgs<Datum>) => string;
+
+/**
+ * Paging button callback
+ */
+export type PagingButtonCallback<Datum = any> = (node: OrgChartNode<Datum>, index: number, array: OrgChartNode<Datum>[], state: OrgChartAttrs<Datum>) => string;
+
+/**
+ * Node update callbacks for DOM manipulation
+ */
+export type NodeUpdateCallback<Datum = any> = (this: SVGGElement, node: OrgChartNode<Datum>, index: number, groups: SVGGElement[] | ArrayLike<SVGGElement>) => void;
+
+export type NodeEnterCallback<Datum = any> = (node: OrgChartNode<Datum>) => OrgChartNode<Datum>;
+export type NodeExitCallback<Datum = any> = (node: OrgChartNode<Datum>) => OrgChartNode<Datum>;
+
+/**
+ * Link update callback for DOM manipulation
+ */
+export type LinkUpdateCallback<Datum = any> = (this: SVGPathElement, node: OrgChartNode<Datum>, index: number, groups: SVGPathElement[] | ArrayLike<SVGPathElement>) => void;
+
+/**
+ * Defs (SVG definitions) generator callback
+ */
+export type DefsCallback<Datum = any> = (state: OrgChartAttrs<Datum>, connections: Connection<Datum>[]) => string;
+
+export type ConnectionsUpdateCallback<Datum = any> = (this: SVGPathElement, d: Connection<Datum>, i: number, arr: SVGPathElement[] | ArrayLike<SVGPathElement>) => void;
+
+// ============================================================================
+// Layout System Types
+// ============================================================================
+
+/**
+ * Supported layout directions
+ */
+export type LayoutType = 'top' | 'left' | 'right' | 'bottom';
+
+/**
+ * Parameters for coordinate transformations
+ */
+export interface PositionParams {
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+}
+
+/**
+ * Point coordinates
+ */
+export interface Point {
+	x: number;
+	y: number;
+}
+
+/**
+ * Compact dimension sizing functions
+ */
+export interface CompactDimension<Datum = any> {
+	sizeColumn: (node: OrgChartNode<Datum>) => number;
+	sizeRow: (node: OrgChartNode<Datum>) => number;
+	reverse: <T>(arr: T[]) => T[];
+}
+
+/**
+ * Layout-specific coordinate and rendering functions
+ */
+export interface LayoutBinding<Datum = any> {
+	// Node boundary positions
+	nodeLeftX: (node: OrgChartNode<Datum>) => number;
+	nodeRightX: (node: OrgChartNode<Datum>) => number;
+	nodeTopY: (node: OrgChartNode<Datum>) => number;
+	nodeBottomY: (node: OrgChartNode<Datum>) => number;
+
+	// Animation entry points
+	nodeJoinX: (params: PositionParams) => number;
+	nodeJoinY: (params: PositionParams) => number;
+
+	// Link connection points
+	linkJoinX: (params: PositionParams) => number;
+	linkJoinY: (params: PositionParams) => number;
+	linkX: (node: OrgChartNode<Datum>) => number;
+	linkY: (node: OrgChartNode<Datum>) => number;
+	linkParentX: (node: OrgChartNode<Datum>) => number;
+	linkParentY: (node: OrgChartNode<Datum>) => number;
+
+	// Compact layout link positions
+	linkCompactXStart: (node: OrgChartNode<Datum>) => number;
+	linkCompactYStart: (node: OrgChartNode<Datum>) => number;
+	compactLinkMidX: (node: OrgChartNode<Datum>, state: OrgChartAttrs<Datum>) => number;
+	compactLinkMidY: (node: OrgChartNode<Datum>, state: OrgChartAttrs<Datum>) => number;
+
+	// Button positioning
+	buttonX: (node: OrgChartNode<Datum>) => number;
+	buttonY: (node: OrgChartNode<Datum>) => number;
+
+	// Transform functions
+	centerTransform: (params: { root: OrgChartNode<Datum>; rootMargin: number; scale: number; centerX: number; centerY: number }) => string;
+	nodeUpdateTransform: (node: OrgChartNode<Datum>, state: OrgChartAttrs<Datum>) => string;
+	zoomTransform: (transform: { x: number; y: number; k: number }) => string;
+
+	// Flex layout
+	nodeFlexSize: (params: { height: number; width: number; siblingsMargin: number; childrenMargin: number; state: OrgChartAttrs<Datum>; node: OrgChartNode<Datum> }) => [number, number];
+
+	// Compact dimensions
+	compactDimension: CompactDimension<Datum>;
+
+	// Link path generators
+	diagonal: (source: Point, target: Point, mid?: Point | null, offsets?: { sy?: number; ty?: number }) => string;
+
+	hdiagonal?: (source: Point, target: Point, mid?: Point | null, offsets?: { sx?: number; tx?: number }) => string;
+
+	// Coordinate swap for layout transformations
+	swap: (node: OrgChartNode<Datum>) => void;
+}
+
+// ============================================================================
+// Main Configuration Interface
+// ============================================================================
+
+/**
+ * Calculated properties derived from configuration
+ */
+export interface CalcProperties {
+	id: string;
+	chartWidth: number;
+	chartHeight: number;
+	centerX: number;
+	centerY: number;
+}
+
+/**
+ * Text measurement parameters
+ */
+export interface TextMeasurementParams {
+	fontSize?: string | number;
+	fontWeight?: string;
+	defaultFont: string;
+	ctx: CanvasRenderingContext2D;
+}
+
+/**
+ * Complete chart configuration and state
+ */
+export interface OrgChartAttrs<Datum = any> {
+	// ========== Internal/Private Properties ==========
+	id: string;
+	firstDraw: boolean;
+	ctx: CanvasRenderingContext2D;
+	initialExpandLevel: number;
+	nodeDefaultBackground: string;
+	lastTransform: { x: number; y: number; k: number };
+	allowedNodesCount: Record<string, number>;
+	zoomBehavior: ZoomBehavior<SVGSVGElement, Datum> | null;
+	generateRoot: ((data: Datum[]) => OrgChartNode<Datum>) | null;
+
+	// Calculated properties
+	calc?: CalcProperties;
+
+	// Hierarchy data
+	allNodes?: OrgChartNode<Datum>[];
+	root?: OrgChartNode<Datum>;
+
+	// Flextree layout instance
+	flexTreeLayout?: FlextreeLayout<Datum>;
+
+	// ========== SVG Elements ==========
+	svg?: Selection<SVGSVGElement, unknown, null, undefined>;
+	chart?: Selection<SVGGElement, unknown, null, undefined>;
+	centerG?: Selection<SVGGElement, unknown, null, undefined>;
+	linksWrapper?: Selection<SVGGElement, unknown, null, undefined>;
+	nodesWrapper?: Selection<SVGGElement, unknown, null, undefined>;
+	connectionsWrapper?: Selection<SVGGElement, unknown, null, undefined>;
+	defsWrapper?: Selection<SVGGElement, unknown, null, undefined>;
+
+	// ========== Public Configuration ==========
+	svgWidth: number;
+	svgHeight: number;
+	container: string | HTMLElement;
+	data: Datum[] | null;
+	connections: Connection<Datum>[];
+	defaultFont: string;
+
+	// ========== Data Accessors ==========
+	nodeId: DataAccessor<string | number, Datum>;
+	parentNodeId: DataAccessor<string | number, Datum>;
+
+	// ========== Layout Configuration ==========
+	rootMargin: number;
+	nodeWidth: NodeAccessor<number, Datum>;
+	nodeHeight: NodeAccessor<number, Datum>;
+	neighbourMargin: (node1: OrgChartNode<Datum>, node2: OrgChartNode<Datum>) => number;
+	siblingsMargin: NodeAccessor<number, Datum>;
+	childrenMargin: NodeAccessor<number, Datum>;
+	compactMarginPair: NodeAccessor<number, Datum>;
+	compactMarginBetween: NodeAccessor<number, Datum>;
+
+	// ========== Button Configuration ==========
+	nodeButtonWidth: NodeAccessor<number, Datum>;
+	nodeButtonHeight: NodeAccessor<number, Datum>;
+	nodeButtonX: NodeAccessor<number, Datum>;
+	nodeButtonY: NodeAccessor<number, Datum>;
+
+	// ========== Behavior Configuration ==========
+	linkYOffset: number;
+	pagingStep: NodeAccessor<number, Datum>;
+	minPagingVisibleNodes: NodeAccessor<number, Datum>;
+	scaleExtent: [number, number];
+	duration: number;
+	imageName: string;
+	setActiveNodeCentered: boolean;
+	layout: LayoutType;
+	compact: boolean;
+
+	// ========== Zoom Behavior ==========
+	createZoom: (node: OrgChartNode<Datum>) => ZoomBehavior<SVGSVGElement, Datum>;
+
+	// ========== Event Callbacks ==========
+	onZoomStart: ZoomCallback<Datum>;
+	onZoom: ZoomCallback<Datum>;
+	onZoomEnd: ZoomCallback<Datum>;
+	onNodeClick: NodeClickCallback<Datum>;
+	onExpandOrCollapse: NodeExpandCollapseCallback<Datum>;
+
+	// ========== Content Generators ==========
+	nodeContent: NodeContentCallback<Datum>;
+	buttonContent: ButtonContentCallback<Datum>;
+	pagingButton: PagingButtonCallback<Datum>;
+	defs: DefsCallback<Datum>;
+
+	// ========== DOM Update Callbacks ==========
+	nodeUpdate: NodeUpdateCallback<Datum>;
+	nodeEnter: NodeEnterCallback<Datum>;
+	nodeExit: NodeExitCallback<Datum>;
+	linkUpdate: LinkUpdateCallback<Datum>;
+	connectionsUpdate: ConnectionsUpdateCallback<Datum>;
+
+	// ========== D3 Generators ==========
+	linkGroupArc?: any;
+	hdiagonal?: (s: Point, t: Point, m?: Point | null, offsets?: any) => string;
+	diagonal?: (s: Point, t: Point, m?: Point | null, offsets?: any) => string;
+
+	// ========== Layout Bindings ==========
+	layoutBindings: Record<LayoutType, LayoutBinding<Datum>>;
+}
+
+// ============================================================================
+// Export/Image Related Types
+// ============================================================================
+
+/**
+ * Parameters for image export
+ */
+export interface ExportImageParams {
+	full?: boolean;
+	scale?: number;
+	onLoad?: (img: HTMLImageElement) => void;
+	save?: boolean;
+	backgroundColor?: string;
+}
+
+/**
+ * Parameters for image download
+ */
+export interface DownloadImageParams {
+	node: SVGSVGElement | HTMLCanvasElement;
+	scale?: number;
+	imageName: string;
+	isSvg?: boolean;
+	save?: boolean;
+	backgroundColor?: string;
+	onAlreadySerialized?: (serialized: string) => void;
+	onLoad?: (img: HTMLImageElement) => void;
+}
+
+/**
+ * Parameters for fit operation
+ */
+export interface FitParams {
+	animate?: boolean;
+	nodes?: OrgChartNode[];
+	scale?: boolean;
+	onCompleted?: () => void;
+}
+
+/**
+ * Parameters for zoom to bounds operation
+ */
+export interface ZoomToBoundsParams {
+	x0: number;
+	x1: number;
+	y0: number;
+	y1: number;
+	params?: FitParams;
+}
+
+/**
+ * Update parameters for render updates
+ */
+export interface UpdateParams {
+	x0: number;
+	y0: number;
+	x?: number;
+	y?: number;
+	width: number;
+	height: number;
+}
+
+// ============================================================================
+// OrgChart Class Interface (for reference)
+// ============================================================================
+
+/**
+ * Main OrgChart class interface
+ * Note: Actual implementation uses dynamic getters/setters for all attrs properties
+ */
+export interface OrgChart<Datum = any> {
+	// Core methods
+	render(): this;
+	update(params: UpdateParams): this;
+	clear(): void;
+	getChartState(): OrgChartAttrs<Datum>;
+
+	// Data manipulation
+	addNode(obj: Datum): this;
+	removeNode(nodeId: string | number): this;
+
+	// State management
+	setExpanded(id: string | number, expandedFlag?: boolean): this;
+	setCentered(nodeId: string | number): this;
+	setHighlighted(nodeId: string | number | null): this;
+	setUpToTheRootHighlighted(nodeId: string | number | null): this;
+	clearHighlighting(): this;
+
+	// Tree operations
+	collapse(node: OrgChartNode<Datum>): this;
+	expand(node: OrgChartNode<Datum>): this;
+	collapseAll(): this;
+	expandAll(): this;
+
+	// Navigation
+	fit(params?: FitParams): this;
+	initialZoom(zoomLevel: number): this;
+	zoomIn(): this;
+	zoomOut(): this;
+
+	// Export
+	exportImg(params?: ExportImageParams): void;
+	exportSvg(): void;
+	fullscreen(elem?: HTMLElement): void;
+
+	// Dynamic getters/setters for all attrs properties
+	[key: string]: any;
+}
+
+// ============================================================================
+// D3 Selection Extension
+// ============================================================================
+
+/**
+ * Parameters for the patternify method
+ */
+export interface PatternifyParams {
+	selector: string;
+	tag: string;
+	data?: any[] | ((d: any) => any[]);
+}