feat(design-system): add DsStack component [AR-53842]

.changeset/add-ds-stack.md

@@ -0,0 +1,5 @@
+---
+'@drivenets/design-system': minor
+---
+
+Add `DsStack` layout component

packages/design-system/package.json

@@ -72,7 +72,8 @@
 		"@tanstack/react-virtual": "^3.13.23",
 		"@zag-js/react": "^1.37.0",
 		"@zag-js/steps": "^1.37.0",
-		"classnames": "^2.5.1"
+		"classnames": "^2.5.1",
+		"csstype": "^3.2.3"
 	},
 	"peerDependencies": {
 		"@internationalized/date": "^3.0.0",

packages/design-system/src/components/ds-stack/__tests__/ds-stack.browser.test.tsx

@@ -0,0 +1,133 @@
+import { describe, expect, it } from 'vitest';
+import { page } from 'vitest/browser';
+
+import { DsStack } from '../ds-stack';
+
+describe('DsStack', () => {
+	it('renders children in a flex column by default', async () => {
+		await page.render(
+			<DsStack>
+				<button type="button">First</button>
+				<button type="button">Second</button>
+			</DsStack>,
+		);
+
+		const first = page.getByRole('button', { name: 'First' });
+		const second = page.getByRole('button', { name: 'Second' });
+		await expect.element(first).toBeVisible();
+		await expect.element(second).toBeVisible();
+
+		const firstRect = first.element().getBoundingClientRect();
+		const secondRect = second.element().getBoundingClientRect();
+		expect(secondRect.top).toBeGreaterThanOrEqual(firstRect.bottom);
+	});
+
+	it('renders children in a row when direction is "row"', async () => {
+		await page.render(
+			<DsStack direction="row">
+				<button type="button">Left</button>
+				<button type="button">Right</button>
+			</DsStack>,
+		);
+
+		const left = page.getByRole('button', { name: 'Left' });
+		const right = page.getByRole('button', { name: 'Right' });
+
+		const leftRect = left.element().getBoundingClientRect();
+		const rightRect = right.element().getBoundingClientRect();
+		expect(rightRect.left).toBeGreaterThanOrEqual(leftRect.right);
+	});
+
+	it('applies gap between children', async () => {
+		await page.render(
+			<DsStack direction="row" gap={20}>
+				<button type="button">A</button>
+				<button type="button">B</button>
+			</DsStack>,
+		);
+
+		const a = page.getByRole('button', { name: 'A' });
+		const b = page.getByRole('button', { name: 'B' });
+
+		const aRect = a.element().getBoundingClientRect();
+		const bRect = b.element().getBoundingClientRect();
+		const actualGap = bRect.left - aRect.right;
+		expect(actualGap).toBeCloseTo(20, 0);
+	});
+
+	it('applies alignItems and justifyContent', async () => {
+		await page.render(
+			<DsStack
+				direction="row"
+				justifyContent="center"
+				alignItems="center"
+				style={{ height: 200, width: 400 }}
+			>
+				<button type="button">Centered</button>
+			</DsStack>,
+		);
+
+		const container = page.getByRole('button', { name: 'Centered' }).element().parentElement;
+		expect(container).toBeTruthy();
+		const containerStyle = getComputedStyle(container as Element);
+		expect(containerStyle.justifyContent).toBe('center');
+		expect(containerStyle.alignItems).toBe('center');
+	});
+
+	it('applies flex, flexWrap, and width', async () => {
+		await page.render(
+			<DsStack flex="1" flexWrap="wrap" width="500px">
+				<button type="button">Child</button>
+			</DsStack>,
+		);
+
+		const container = page.getByRole('button', { name: 'Child' }).element().parentElement;
+		expect(container).toBeTruthy();
+		const containerStyle = getComputedStyle(container as Element);
+		expect(containerStyle.flexWrap).toBe('wrap');
+		expect(containerStyle.width).toBe('500px');
+	});
+
+	it('merges custom className and style', async () => {
+		await page.render(
+			<DsStack className="custom-class" style={{ padding: 12 }}>
+				<button type="button">Styled</button>
+			</DsStack>,
+		);
+
+		const container = page.getByRole('button', { name: 'Styled' }).element().parentElement as HTMLElement;
+		expect(container).toBeTruthy();
+		expect(container.classList.contains('custom-class')).toBe(true);
+		expect(container.style.padding).toBe('12px');
+	});
+
+	it('forwards ref to the root div', async () => {
+		let refElement: HTMLDivElement | null = null;
+
+		await page.render(
+			<DsStack
+				ref={(el) => {
+					refElement = el;
+				}}
+			>
+				<button type="button">Ref test</button>
+			</DsStack>,
+		);
+
+		await expect.element(page.getByRole('button', { name: 'Ref test' })).toBeVisible();
+		expect(refElement).toBeInstanceOf(HTMLDivElement);
+	});
+
+	it('user style overrides layout props', async () => {
+		await page.render(
+			<DsStack gap={10} style={{ gap: 30 }}>
+				<button type="button">X</button>
+				<button type="button">Y</button>
+			</DsStack>,
+		);
+
+		const container = page.getByRole('button', { name: 'X' }).element().parentElement as HTMLElement;
+		expect(container).toBeTruthy();
+		expect(container.style.gap).toBe('30px');
+	});
+});

packages/design-system/src/components/ds-stack/ds-stack.module.scss

@@ -0,0 +1,4 @@
+.root {
+	display: flex;
+	flex-direction: column;
+}

packages/design-system/src/components/ds-stack/ds-stack.stories.module.scss

@@ -0,0 +1,15 @@
+.box {
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	min-width: 80px;
+	padding: var(--xs) var(--sm);
+	border: 1px solid var(--color-border-default);
+	border-radius: 4px;
+	background-color: var(--color-bg-surface-1);
+	font-size: var(--font-size-body-md);
+}
+
+.container {
+	width: 600px;
+}

packages/design-system/src/components/ds-stack/ds-stack.stories.tsx

@@ -0,0 +1,123 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { DsStack } from './index';
+import styles from './ds-stack.stories.module.scss';
+
+const Box = ({ children }: { children: React.ReactNode }) => <div className={styles.box}>{children}</div>;
+
+const meta: Meta<typeof DsStack> = {
+	title: 'Design System/Stack',
+	component: DsStack,
+	parameters: {
+		layout: 'centered',
+	},
+	argTypes: {
+		direction: { control: 'select', options: ['row', 'column', 'row-reverse', 'column-reverse'] },
+		gap: { control: 'text' },
+		alignItems: { control: 'select', options: ['flex-start', 'center', 'flex-end', 'stretch', 'baseline'] },
+		justifyContent: {
+			control: 'select',
+			options: ['flex-start', 'center', 'flex-end', 'space-between', 'space-around', 'space-evenly'],
+		},
+		flexWrap: { control: 'select', options: ['nowrap', 'wrap', 'wrap-reverse'] },
+		width: { control: 'text' },
+		flex: { control: 'text' },
+		className: { table: { disable: true } },
+		style: { table: { disable: true } },
+		ref: { table: { disable: true } },
+	},
+};
+
+export default meta;
+
+type Story = StoryObj<typeof DsStack>;
+
+export const Default: Story = {
+	args: {
+		direction: 'column',
+		gap: 8,
+	},
+	render: (args) => (
+		<DsStack {...args}>
+			<Box>Item 1</Box>
+			<Box>Item 2</Box>
+			<Box>Item 3</Box>
+		</DsStack>
+	),
+};
+
+export const Row: Story = {
+	args: {
+		direction: 'row',
+		gap: 16,
+		alignItems: 'center',
+	},
+	render: (args) => (
+		<DsStack {...args}>
+			<Box>Item 1</Box>
+			<Box>Item 2</Box>
+			<Box>Item 3</Box>
+		</DsStack>
+	),
+};
+
+export const Responsive: Story = {
+	args: {
+		direction: { md: 'column', lg: 'row' },
+		gap: { md: 8, lg: 24 },
+		alignItems: 'center',
+	},
+	render: (args) => (
+		<DsStack {...args} className={styles.container}>
+			<Box>Item 1</Box>
+			<Box>Item 2</Box>
+			<Box>Item 3</Box>
+		</DsStack>
+	),
+};
+
+export const SpaceBetween: Story = {
+	args: {
+		direction: 'row',
+		justifyContent: 'space-between',
+		alignItems: 'center',
+		width: '100%',
+	},
+	render: (args) => (
+		<DsStack {...args} className={styles.container}>
+			<Box>Left</Box>
+			<Box>Right</Box>
+		</DsStack>
+	),
+};
+
+export const Wrapping: Story = {
+	args: {
+		direction: 'row',
+		gap: 8,
+		flexWrap: 'wrap',
+	},
+	render: (args) => (
+		<DsStack {...args} className={styles.container}>
+			{Array.from({ length: 10 }, (_, i) => (
+				<Box key={i}>Item {i + 1}</Box>
+			))}
+		</DsStack>
+	),
+};
+
+export const Nested: Story = {
+	render: () => (
+		<DsStack gap={24}>
+			<DsStack direction="row" gap={16} alignItems="center">
+				<Box>Row 1 - A</Box>
+				<Box>Row 1 - B</Box>
+				<Box>Row 1 - C</Box>
+			</DsStack>
+
+			<DsStack direction="row" gap={16} alignItems="center">
+				<Box>Row 2 - A</Box>
+				<Box>Row 2 - B</Box>
+			</DsStack>
+		</DsStack>
+	),
+};

packages/design-system/src/components/ds-stack/ds-stack.tsx

@@ -0,0 +1,35 @@
+import classNames from 'classnames';
+
+import styles from './ds-stack.module.scss';
+import type { DsStackProps } from './ds-stack.types';
+
+export const DsStack = ({
+	direction,
+	gap,
+	alignItems,
+	justifyContent,
+	flex,
+	flexWrap,
+	width,
+	children,
+	className,
+	style,
+	ref,
+}: DsStackProps) => {
+	const layoutStyle: React.CSSProperties = {
+		flexDirection: direction,
+		gap,
+		alignItems,
+		justifyContent,
+		flex,
+		flexWrap,
+		width,
+		...style,
+	};
+
+	return (
+		<div ref={ref} className={classNames(styles.root, className)} style={layoutStyle}>
+			{children}
+		</div>
+	);
+};

packages/design-system/src/components/ds-stack/ds-stack.types.ts

@@ -0,0 +1,19 @@
+import type { Properties } from 'csstype';
+
+type CSSProps = Properties<string | number>;
+import type { CSSProperties, ReactNode, Ref } from 'react';
+
+export interface DsStackProps {
+	direction?: CSSProps['flexDirection'];
+	gap?: CSSProps['gap'];
+	alignItems?: CSSProps['alignItems'];
+	justifyContent?: CSSProps['justifyContent'];
+	flex?: CSSProps['flex'];
+	flexWrap?: CSSProps['flexWrap'];
+	width?: CSSProps['width'];
+
+	children?: ReactNode;
+	className?: string;
+	style?: CSSProperties;
+	ref?: Ref<HTMLDivElement>;
+}

packages/design-system/src/components/ds-stack/index.ts

@@ -0,0 +1,18 @@
+import type { ComponentProps } from 'react';
+
+import { withResponsiveProps } from '../../utils/responsive';
+import { DsStack as DsStackBase } from './ds-stack';
+
+export const DsStack = withResponsiveProps(DsStackBase, [
+	'direction',
+	'gap',
+	'alignItems',
+	'justifyContent',
+	'flex',
+	'flexWrap',
+	'width',
+]);
+
+DsStack.displayName = 'DsStack';
+
+export type DsStackProps = ComponentProps<typeof DsStack>;

packages/design-system/src/index.ts

@@ -43,6 +43,7 @@ export * from './components/ds-select';
 export * from './components/ds-skeleton';
 export * from './components/ds-smart-tabs';
 export * from './components/ds-spinner';
+export * from './components/ds-stack';
 export * from './components/ds-status-badge';
 export * from './components/ds-stepper';
 export * from './components/ds-system-status';