@drivenets/design-system 0.18.1 → 0.20.0

package/src/components/ds-code-input/ds-code-input.utils.unit.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, it, vi } from 'vitest';
+import {
+	applyTextSelection,
+	canonicalizeLf,
+	getAdditionalLineCount,
+	getLineAtIndex,
+	getLineIndexAtOffset,
+	getLogicalLineCount,
+	getSelectedLineCount,
+	type TextSelection,
+} from './ds-code-input.utils';
+
+const multiline = 'SELECT *\nFROM devices\nWHERE id = 1';
+
+const stubTextarea = (value: string) => {
+	const setSelectionRange = vi.fn();
+
+	return {
+		element: { value, setSelectionRange } as unknown as HTMLTextAreaElement,
+		setSelectionRange,
+	};
+};
+
+describe('canonicalizeLf', () => {
+	it('rewrites CRLF to LF', () => {
+		expect(canonicalizeLf('a\r\nb')).toBe('a\nb');
+	});
+
+	it('rewrites a lone CR to LF', () => {
+		expect(canonicalizeLf('a\rb')).toBe('a\nb');
+	});
+
+	it('leaves LF unchanged', () => {
+		expect(canonicalizeLf('a\nb')).toBe('a\nb');
+	});
+
+	it('normalizes mixed endings in one string', () => {
+		expect(canonicalizeLf('a\r\nb\rc\nd')).toBe('a\nb\nc\nd');
+	});
+});
+
+describe('getLogicalLineCount', () => {
+	it('counts an empty string as one logical line', () => {
+		expect(getLogicalLineCount('')).toBe(1);
+	});
+
+	it('counts a trailing newline as an extra empty line', () => {
+		expect(getLogicalLineCount('a\n')).toBe(2);
+	});
+
+	it('counts each logical line in multiline text', () => {
+		expect(getLogicalLineCount(multiline)).toBe(3);
+	});
+});
+
+describe('getAdditionalLineCount', () => {
+	it('is zero for a single line, including empty text', () => {
+		expect(getAdditionalLineCount('')).toBe(0);
+		expect(getAdditionalLineCount('SELECT *')).toBe(0);
+	});
+
+	it('is the number of lines beyond the first', () => {
+		expect(getAdditionalLineCount('a\n')).toBe(1);
+		expect(getAdditionalLineCount(multiline)).toBe(2);
+	});
+});
+
+describe('getLineAtIndex', () => {
+	it('returns the line at a valid index', () => {
+		expect(getLineAtIndex(multiline, 0)).toBe('SELECT *');
+		expect(getLineAtIndex(multiline, 1)).toBe('FROM devices');
+		expect(getLineAtIndex(multiline, 2)).toBe('WHERE id = 1');
+	});
+
+	it('returns an empty string when the index is out of range', () => {
+		expect(getLineAtIndex(multiline, -1)).toBe('');
+		expect(getLineAtIndex(multiline, 3)).toBe('');
+	});
+
+	it('splits CRLF text on logical lines', () => {
+		expect(getLineAtIndex('hello\r\nworld', 0)).toBe('hello');
+		expect(getLineAtIndex('hello\r\nworld', 1)).toBe('world');
+	});
+});
+
+describe('getLineIndexAtOffset', () => {
+	const text = 'hello\nworld';
+
+	it('returns the first line at the start of the text', () => {
+		expect(getLineIndexAtOffset(text, 0)).toBe(0);
+	});
+
+	it('stays on the previous line when the offset sits on a newline', () => {
+		expect(getLineIndexAtOffset(text, 5)).toBe(0);
+	});
+
+	it('moves to the next line once the offset is past the newline', () => {
+		expect(getLineIndexAtOffset(text, 6)).toBe(1);
+	});
+
+	it('clamps offsets below 0 and past the text length', () => {
+		expect(getLineIndexAtOffset(text, -4)).toBe(0);
+		expect(getLineIndexAtOffset(text, 100)).toBe(1);
+	});
+
+	it('maps offsets in CRLF text onto the same logical lines as LF', () => {
+		const crlf = 'hello\r\nworld';
+
+		expect(getLineIndexAtOffset(crlf, 5)).toBe(0);
+		expect(getLineIndexAtOffset(crlf, 6)).toBe(1);
+		expect(getLineIndexAtOffset(crlf, crlf.length)).toBe(1);
+	});
+});
+
+describe('getSelectedLineCount', () => {
+	const text = 'a\nb\nc';
+
+	it('is zero when the range is collapsed, even in multiline text', () => {
+		expect(getSelectedLineCount(text, 0, 0)).toBe(0);
+		expect(getSelectedLineCount(text, 2, 2)).toBe(0);
+	});
+
+	it('is one when the range stays on a single line', () => {
+		expect(getSelectedLineCount(text, 0, 1)).toBe(1);
+	});
+
+	it('counts each line the range crosses', () => {
+		expect(getSelectedLineCount(text, 0, 2)).toBe(2);
+		expect(getSelectedLineCount(text, 0, text.length)).toBe(3);
+	});
+
+	it('treats a reversed range the same as start-to-end', () => {
+		expect(getSelectedLineCount(text, 2, 0)).toBe(getSelectedLineCount(text, 0, 2));
+	});
+
+	it('stays on one line when the range ends on a newline', () => {
+		expect(getSelectedLineCount('hello\nworld', 0, 5)).toBe(1);
+	});
+});
+
+describe('applyTextSelection', () => {
+	it('restores the range and direction on the element', () => {
+		const { element, setSelectionRange } = stubTextarea('abc');
+		const selection: TextSelection = { start: 1, end: 2, direction: 'forward' };
+
+		applyTextSelection(element, selection);
+
+		expect(setSelectionRange).toHaveBeenCalledWith(1, 2, 'forward');
+	});
+
+	it('clamps the range to the current value length', () => {
+		const { element, setSelectionRange } = stubTextarea('abc');
+
+		applyTextSelection(element, { start: 10, end: 20, direction: 'none' });
+
+		expect(setSelectionRange).toHaveBeenCalledWith(3, 3, 'none');
+	});
+
+	it('clamps only the end when start is still in range', () => {
+		const { element, setSelectionRange } = stubTextarea('abc');
+
+		applyTextSelection(element, { start: 1, end: 99, direction: 'backward' });
+
+		expect(setSelectionRange).toHaveBeenCalledWith(1, 3, 'backward');
+	});
+});

package/src/components/ds-code-input/index.ts

@@ -0,0 +1,2 @@
+export { default as DsCodeInput } from './ds-code-input';
+export * from './ds-code-input.types';

package/src/components/ds-code-input/use-collapsed-viewport.ts

@@ -0,0 +1,289 @@
+import { type Dispatch, type RefObject, type SetStateAction, useEffect, useState } from 'react';
+import {
+	getAdditionalLineCount,
+	getLineAtIndex,
+	getLineIndexAtOffset,
+	getLogicalLineCount,
+	getSelectedLineCount,
+	getVisibleLineIndex,
+	measureTextWidth,
+	scrollToLogicalLine,
+} from './ds-code-input.utils';
+
+const CARET_INLINE_PADDING_PX = 16;
+
+export type CollapsedIndicator =
+	| { kind: 'plusN'; count: number }
+	| { kind: 'line'; current: number; total: number }
+	| { kind: 'selection'; selected: number; total: number };
+
+export interface CollapsedViewport {
+	focused: boolean;
+	visibleLine: number;
+	caretLine: number;
+	totalLines: number;
+	indicator: CollapsedIndicator | null;
+	fadeStart: boolean;
+	fadeEnd: boolean;
+	showEllipsis: boolean;
+	echoText: string;
+	revealCaretLine: () => void;
+}
+
+export interface CollapsedViewportHandlers {
+	onSelect: () => void;
+	onKeyUp: () => void;
+	onClick: () => void;
+	onScroll: () => void;
+	onFocus: () => void;
+	onBlur: () => void;
+	onBeforeInput: () => void;
+}
+
+interface ViewportSnapshot {
+	totalLines: number;
+	caretLine: number;
+	visibleLine: number;
+	selectedLines: number;
+	clipped: boolean;
+	fadeStart: boolean;
+	fadeEnd: boolean;
+}
+
+const initialSnapshot: ViewportSnapshot = {
+	totalLines: 1,
+	caretLine: 1,
+	visibleLine: 1,
+	selectedLines: 0,
+	clipped: false,
+	fadeStart: false,
+	fadeEnd: false,
+};
+
+const snapshotsEqual = (left: ViewportSnapshot, right: ViewportSnapshot) =>
+	left.totalLines === right.totalLines &&
+	left.caretLine === right.caretLine &&
+	left.visibleLine === right.visibleLine &&
+	left.selectedLines === right.selectedLines &&
+	left.clipped === right.clipped &&
+	left.fadeStart === right.fadeStart &&
+	left.fadeEnd === right.fadeEnd;
+
+const readViewport = (textarea: HTMLTextAreaElement): ViewportSnapshot => {
+	const value = textarea.value;
+	const totalLines = getLogicalLineCount(value);
+	const caretLine = getLineIndexAtOffset(value, textarea.selectionStart) + 1;
+	const visibleLine = Math.min(getVisibleLineIndex(textarea) + 1, totalLines);
+	const selectedLines = getSelectedLineCount(value, textarea.selectionStart, textarea.selectionEnd);
+	const visibleText = getLineAtIndex(value, visibleLine - 1);
+	const clipped = measureTextWidth(textarea, visibleText) > textarea.clientWidth;
+	const fadeStart = textarea.scrollLeft > 0;
+	const fadeEnd = textarea.scrollLeft + textarea.clientWidth < textarea.scrollWidth - 1;
+
+	return {
+		totalLines,
+		caretLine,
+		visibleLine,
+		selectedLines,
+		clipped,
+		fadeStart,
+		fadeEnd,
+	};
+};
+
+const commitViewport = (
+	textarea: HTMLTextAreaElement,
+	setSnapshot: Dispatch<SetStateAction<ViewportSnapshot>>,
+) => {
+	const next = readViewport(textarea);
+
+	setSnapshot((current) => (snapshotsEqual(current, next) ? current : next));
+};
+
+/**
+ * The collapsed field shows one logical line. This hook tracks which line is
+ * visible, where the caret is, overflow fades, and the +N / Ln x/y / selection chip.
+ */
+export const useCollapsedViewport = (
+	textareaRef: RefObject<HTMLTextAreaElement | null>,
+	value: string,
+	ready: boolean,
+	collapsed: boolean,
+): CollapsedViewport & CollapsedViewportHandlers => {
+	const [focused, setFocused] = useState(false);
+	const [snapshot, setSnapshot] = useState(initialSnapshot);
+
+	const sync = () => {
+		const textarea = textareaRef.current;
+
+		if (textarea) {
+			commitViewport(textarea, setSnapshot);
+		}
+	};
+
+	// Scroll so the caret line is the one visible row (used after collapse).
+	const revealCaretLine = () => {
+		const textarea = textareaRef.current;
+
+		if (!textarea) {
+			return;
+		}
+
+		const lineIndex = getLineIndexAtOffset(textarea.value, textarea.selectionStart);
+
+		scrollToLogicalLine(textarea, lineIndex);
+		textarea.scrollLeft = Math.max(0, textarea.scrollLeft - CARET_INLINE_PADDING_PX);
+		setSnapshot((current) => ({
+			...current,
+			visibleLine: lineIndex + 1,
+			caretLine: lineIndex + 1,
+		}));
+	};
+
+	const onSelect = sync;
+	const onKeyUp = sync;
+	const onClick = sync;
+
+	const onScroll = () => {
+		if (collapsed) {
+			sync();
+		}
+	};
+
+	const onFocus = () => {
+		if (!collapsed) {
+			return;
+		}
+
+		setFocused(true);
+		revealCaretLine();
+		sync();
+	};
+
+	const onBlur = () => {
+		if (!collapsed) {
+			return;
+		}
+
+		const textarea = textareaRef.current;
+
+		setFocused(false);
+
+		if (textarea) {
+			// Idle field always shows the start of the document.
+			scrollToLogicalLine(textarea, 0);
+			textarea.scrollLeft = 0;
+		}
+
+		sync();
+	};
+
+	const onBeforeInput = () => {
+		if (!collapsed) {
+			return;
+		}
+
+		const textarea = textareaRef.current;
+
+		if (!textarea) {
+			return;
+		}
+
+		const next = readViewport(textarea);
+
+		// Typing while looking at another line: jump to the caret line first.
+		if (next.caretLine !== next.visibleLine) {
+			revealCaretLine();
+		}
+	};
+
+	useEffect(() => {
+		const textarea = textareaRef.current;
+
+		if (!textarea || !ready) {
+			setFocused(false);
+
+			return;
+		}
+
+		const syncFromDom = () => commitViewport(textarea, setSnapshot);
+
+		// React's onSelect is backed by selectionchange, so programmatic
+		// `select` events (tests, setSelectionRange) still need a native listener.
+		textarea.addEventListener('select', syncFromDom);
+
+		// Line-by-line, not native pixel scroll — a one-row textarea would
+		// otherwise feel broken. React's onWheel is passive, so this stays native.
+		const handleWheel = (event: WheelEvent) => {
+			if (document.activeElement !== textarea || event.deltaY === 0) {
+				return;
+			}
+
+			const next = readViewport(textarea);
+			const direction = event.deltaY > 0 ? 1 : -1;
+			const nextLine = next.visibleLine + direction;
+
+			if (nextLine < 1 || nextLine > next.totalLines) {
+				return;
+			}
+
+			event.preventDefault();
+			scrollToLogicalLine(textarea, nextLine - 1);
+			syncFromDom();
+		};
+
+		let observer: ResizeObserver | undefined;
+
+		if (collapsed) {
+			textarea.addEventListener('wheel', handleWheel, { passive: false });
+			setFocused(document.activeElement === textarea);
+			observer = new ResizeObserver(syncFromDom);
+			observer.observe(textarea);
+		} else {
+			setFocused(false);
+		}
+
+		syncFromDom();
+
+		return () => {
+			textarea.removeEventListener('select', syncFromDom);
+			textarea.removeEventListener('wheel', handleWheel);
+			observer?.disconnect();
+		};
+	}, [ready, collapsed, value, textareaRef]);
+
+	const additional = getAdditionalLineCount(value);
+	// Caret line, painted as a static stand-in while the real textarea lives in the overlay.
+	const echoText = getLineAtIndex(value, snapshot.caretLine - 1);
+
+	// Selection spanning lines > focused line position > idle +N.
+	let indicator: CollapsedIndicator | null = null;
+
+	if (snapshot.selectedLines > 1) {
+		indicator = { kind: 'selection', selected: snapshot.selectedLines, total: snapshot.totalLines };
+	} else if (focused && additional > 0) {
+		indicator = { kind: 'line', current: snapshot.visibleLine, total: snapshot.totalLines };
+	} else if (!focused && additional > 0) {
+		indicator = { kind: 'plusN', count: additional };
+	}
+
+	return {
+		focused,
+		visibleLine: snapshot.visibleLine,
+		caretLine: snapshot.caretLine,
+		totalLines: Math.max(snapshot.totalLines, getLogicalLineCount(value)),
+		indicator,
+		fadeStart: focused && snapshot.fadeStart,
+		fadeEnd: focused && snapshot.fadeEnd,
+		showEllipsis: (!focused || !collapsed || !ready) && snapshot.clipped,
+		echoText,
+		revealCaretLine,
+		onSelect,
+		onKeyUp,
+		onClick,
+		onScroll,
+		onFocus,
+		onBlur,
+		onBeforeInput,
+	};
+};

package/src/components/ds-code-input/use-editor-host.ts

@@ -0,0 +1,87 @@
+import { type RefObject, useLayoutEffect, useRef, useState } from 'react';
+import { applyTextSelection, type TextSelection } from './ds-code-input.utils';
+
+interface UseEditorHostOptions {
+	isExpanded: boolean;
+	collapsedSlotRef: RefObject<HTMLDivElement | null>;
+	overlaySlotRef: RefObject<HTMLDivElement | null>;
+	hostClassName?: string;
+	textareaRef: RefObject<HTMLTextAreaElement | null>;
+	pendingSelectionRef: RefObject<TextSelection | null>;
+	shouldFocus: boolean;
+}
+
+/**
+ * One host div for the textarea. Attach it to the current slot (collapsed or
+ * overlay), then the component portals the same textarea into that host.
+ */
+export const useEditorHost = ({
+	isExpanded,
+	collapsedSlotRef,
+	overlaySlotRef,
+	hostClassName,
+	textareaRef,
+	pendingSelectionRef,
+	shouldFocus,
+}: UseEditorHostOptions) => {
+	const [hostReady, setHostReady] = useState(false);
+	const hostRef = useRef<HTMLDivElement | null>(null);
+	// True only while appendChild runs, so the component can swallow the
+	// focus/blur that moving a focused node fires.
+	const isMovingHostRef = useRef(false);
+
+	useLayoutEffect(() => {
+		if (hostRef.current === null) {
+			hostRef.current = document.createElement('div');
+		}
+
+		const host = hostRef.current;
+		const dest = isExpanded ? overlaySlotRef.current : collapsedSlotRef.current;
+
+		if (!dest) {
+			return;
+		}
+
+		isMovingHostRef.current = true;
+		host.className = hostClassName ?? '';
+
+		if (host.parentElement !== dest) {
+			dest.appendChild(host);
+		}
+
+		const textarea = textareaRef.current;
+		const pending = pendingSelectionRef.current;
+
+		// Put the caret back, then focus only if the user opened the overlay
+		// (not if it opened from outside).
+		if (textarea && pending) {
+			applyTextSelection(textarea, pending);
+			pendingSelectionRef.current = null;
+		}
+
+		if (textarea && shouldFocus) {
+			textarea.focus({ preventScroll: true });
+		}
+
+		isMovingHostRef.current = false;
+
+		if (!hostReady) {
+			setHostReady(true);
+		}
+	}, [
+		isExpanded,
+		hostReady,
+		shouldFocus,
+		hostClassName,
+		collapsedSlotRef,
+		overlaySlotRef,
+		textareaRef,
+		pendingSelectionRef,
+	]);
+
+	return {
+		host: hostRef.current,
+		hostReady,
+		isMovingHostRef,
+	};
+};

package/src/components/ds-dropdown-menu/ds-dropdown-menu.tsx

@@ -114,9 +114,11 @@ const Item: React.FC<DsDropdownMenuItemProps> = ({
 	children,
 	className,
 	style,
+	...rest
 }) => {
 	return (
 		<Menu.Item
+			{...rest}
 			disabled={disabled}
 			className={classNames(
 				styles.item,

package/src/components/ds-empty-state/ds-empty-state.module.scss

@@ -0,0 +1,16 @@
+.root {
+	text-align: center;
+}
+
+.illustration {
+	flex-shrink: 0;
+	width: 250px;
+	height: 200px;
+	max-width: 100%;
+
+	svg {
+		display: block;
+		width: 100%;
+		height: 100%;
+	}
+}

package/src/components/ds-empty-state/ds-empty-state.tsx

@@ -0,0 +1,45 @@
+import classNames from 'classnames';
+import { DsIllustration } from '../ds-illustration';
+import { DsStack } from '../ds-stack';
+import { DsTypography } from '../ds-typography';
+import styles from './ds-empty-state.module.scss';
+import { defaultDsEmptyStateMessages, type DsEmptyStateProps } from './ds-empty-state.types';
+
+/**
+ * Centered empty-state cluster: illustration, message, and an optional action.
+ *
+ * Use `noData` when the collection has no records and `noMatches` when a search
+ * or filter yielded zero items. Pass `action` for a consumer-owned button.
+ */
+const DsEmptyState = ({
+	variant = 'noData',
+	message,
+	illustration,
+	action,
+	className,
+	style,
+	ref,
+}: DsEmptyStateProps) => {
+	illustration ??= <DsIllustration variant={variant === 'noMatches' ? 'no-search-result' : 'empty-inbox'} />;
+	const resolvedMessage = message ?? defaultDsEmptyStateMessages[variant];
+
+	return (
+		<div ref={ref} className={classNames(styles.root, className)} style={style} role="status">
+			<DsStack direction="column" alignItems="center" justifyContent="center" gap="var(--xs)">
+				<div className={styles.illustration} aria-hidden="true">
+					{illustration}
+				</div>
+				<DsStack direction="column" alignItems="center" gap="var(--lg)">
+					<DsTypography variant="body-md-reg" color="var(--color-dap-gray-700)">
+						{resolvedMessage}
+					</DsTypography>
+					{action}
+				</DsStack>
+			</DsStack>
+		</div>
+	);
+};
+
+DsEmptyState.displayName = 'DsEmptyState';
+
+export default DsEmptyState;

package/src/components/ds-empty-state/ds-empty-state.types.ts

@@ -0,0 +1,38 @@
+import type { CSSProperties, ReactNode, Ref } from 'react';
+
+export const dsEmptyStateVariants = ['noData', 'noMatches'] as const;
+export type DsEmptyStateVariant = (typeof dsEmptyStateVariants)[number];
+
+export const defaultDsEmptyStateMessages: Record<DsEmptyStateVariant, string> = Object.freeze({
+	noData: 'No data to display.',
+	noMatches: 'No matching records found.',
+});
+
+export interface DsEmptyStateProps {
+	/**
+	 * Which empty-state reason to present.
+	 * @default 'noData'
+	 */
+	variant?: DsEmptyStateVariant;
+
+	/**
+	 * Overrides the default copy for the active variant.
+	 */
+	message?: string;
+
+	/**
+	 * Replaces the bundled illustration for the active variant.
+	 */
+	illustration?: ReactNode;
+
+	/**
+	 * Optional action, typically a button. Omitted from the table's inferred default.
+	 */
+	action?: ReactNode;
+
+	className?: string;
+
+	style?: CSSProperties;
+
+	ref?: Ref<HTMLDivElement>;
+}

package/src/components/ds-empty-state/index.ts

@@ -0,0 +1,3 @@
+export { default as DsEmptyState } from './ds-empty-state';
+export type { DsEmptyStateProps, DsEmptyStateVariant } from './ds-empty-state.types';
+export { dsEmptyStateVariants } from './ds-empty-state.types';

package/src/components/ds-file-upload/ds-file-upload.tsx

@@ -4,7 +4,10 @@ import { FileUpload } from './components/file-upload';
 import { useFileUpload } from './hooks';
 
 /**
- * Design system File Upload component (with state management)
+ * File upload with built-in state management (progress, retries, cancellation).
+ *
+ * Pass an `adapter` implementing `FileUploadAdapter` to connect it to your backend:
+ * `const adapter = getSimpleFileUploadAdapter('/api/upload')`.
  */
 const DsFileUpload: React.FC<DsFileUploadProps> = ({
 	adapter,

package/src/components/ds-filters-bar/components/ds-filters-bar-builder/ds-filters-bar-builder.ts

@@ -0,0 +1,11 @@
+import type { FC } from 'react';
+import { useDsFiltersBarContext } from '../../ds-filters-bar.context';
+import type { DsFiltersBarBuilderProps } from './ds-filters-bar-builder.types';
+
+export const Builder: FC<DsFiltersBarBuilderProps> = () => {
+	useDsFiltersBarContext();
+
+	return null;
+};
+
+Builder.displayName = 'DsFiltersBar.Builder';