feat(design-system): add "DsIllustration" component [AR-77735]

.changeset/great-papers-yawn.md

@@ -0,0 +1,5 @@
+---
+'@drivenets/design-system': patch
+---
+
+Add `DsIllustration` component

CONTEXT.md

@@ -48,6 +48,14 @@ _Avoid_: sub props, child props
 Content a **Component** renders when it has genuinely zero data items. Distinct from a loading/skeleton state and from a transient frame where a virtualized body has not yet produced rows. Gate it on data count, never on rendered/virtual row count.
 _Avoid_: no-data view, blank state, placeholder
 
+**Icon**:
+A monochrome glyph rendered by `DsIcon` — Material Symbols or a `special-*` custom SVG — at 16–32px, tinted with `currentColor`.
+_Avoid_: rich icon, state icon (those tiles are **Illustrations**)
+
+**Illustration**:
+A 250×200 colorful empty-screen tile rendered by `DsIllustration` (clouds plus a scene). Not an **Icon**.
+_Avoid_: rich icon, DAP_State Icon (as a code name), Cluster NE (for the Device tile)
+
 **Successor component**:
 A new **Component** folder that supersedes an older one while the old export remains (often `ds-{name}-v2` or `ds-{name}-v3`). Mark the old API `@deprecated` in types and stories; prefer the successor in new code.
 _Avoid_: replacement, v2 component (as a synonym for the pattern name)

packages/design-system/src/components/ds-illustration/__tests__/__snapshots__/ds-illustration.docs.snap

@@ -0,0 +1,9 @@
+# DsIllustration docs snippets
+
+## Default
+
+### Show code
+<DsIllustration variant="no-tasks" />
+
+### MCP manifest
+const Default = () => <DsIllustration variant="no-tasks" />;

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

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { page } from 'vitest/browser';
+import { DsIllustration } from '../index';
+
+describe('DsIllustration', () => {
+	it('is decorative by default and exposes a label when asked', async () => {
+		const { container, rerender } = await page.render(<DsIllustration variant="device" />);
+		const svg = container.querySelector('svg');
+
+		expect(svg).toHaveAttribute('aria-hidden', 'true');
+
+		await rerender(<DsIllustration variant="device" aria-hidden={false} aria-label="Device scene" />);
+
+		await expect.element(page.getByLabelText('Device scene')).toBeVisible();
+	});
+});

packages/design-system/src/components/ds-illustration/ds-illustration.figma.ts

@@ -0,0 +1,34 @@
+// url=https://www.figma.com/design/nha3m67y7S57cHCSuQO2gp/DAP-Design-System-1.2?node-id=27983-34300
+// source=https://github.com/drivenets/design-system/tree/main/packages/design-system/src/components/ds-illustration
+// component=DsIllustration
+import figma from 'figma';
+
+const instance = figma.selectedInstance;
+
+const variant =
+	instance.getEnum('Property 1', {
+		Done: 'done',
+		EmptyInbox: 'empty-inbox',
+		Error: 'error',
+		NoConnection: 'no-connection',
+		NoCreditCard: 'no-credit-card',
+		NoDocuments: 'no-documents',
+		NoGPS: 'no-gps',
+		NoImages: 'no-images',
+		NoItemsCart: 'no-items-cart',
+		NoMessages: 'no-messages',
+		NoSearchResult: 'no-search-result',
+		NoTasks: 'no-tasks',
+		'No Device': 'no-device',
+		'Go Filter': 'go-filter',
+		Device: 'device',
+		Site: 'site',
+		configuration: 'configuration',
+	}) ?? 'no-tasks';
+
+export default {
+	example: figma.code`<DsIllustration variant="${variant}" />`,
+	imports: ["import { DsIllustration } from '@drivenets/design-system';"],
+	id: 'ds-illustration',
+	metadata: { nestable: true },
+} satisfies figma.Template;

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

@@ -0,0 +1,6 @@
+.root {
+	display: block;
+	width: 250px;
+	height: 200px;
+	max-width: 100%;
+}

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

@@ -0,0 +1,6 @@
+.showcase {
+	display: grid;
+	grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));
+	gap: var(--standard);
+	padding: var(--standard);
+}

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

@@ -0,0 +1,52 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { DsTypography } from '../ds-typography';
+import { DsIllustration } from './index';
+import { dsIllustrationVariants } from './ds-illustration.types';
+import styles from './ds-illustration.stories.module.scss';
+import { DsStack } from '../ds-stack';
+
+const meta: Meta<typeof DsIllustration> = {
+	title: 'Components/Illustration',
+	component: DsIllustration,
+	parameters: { layout: 'centered' },
+	argTypes: {
+		variant: { control: 'select', options: dsIllustrationVariants },
+		className: { table: { disable: true } },
+		style: { table: { disable: true } },
+		ref: { table: { disable: true } },
+		'aria-hidden': { table: { disable: true } },
+		'aria-label': { table: { disable: true } },
+	},
+};
+
+export default meta;
+type Story = StoryObj<typeof DsIllustration>;
+
+export const Default: Story = {
+	args: {
+		variant: 'no-tasks',
+	},
+};
+
+/**
+ * Every published tile. Visual catalog only — pick a `variant` in product code.
+ */
+export const Showcase: Story = {
+	tags: ['!manifest'],
+	parameters: {
+		layout: 'fullscreen',
+		docs: { canvas: { sourceState: 'none' } },
+	},
+	render: () => (
+		<div className={styles.showcase}>
+			{dsIllustrationVariants.map((variant) => (
+				<DsStack key={variant} direction="column" alignItems="center" gap="var(--xs)">
+					<DsIllustration variant={variant} />
+					<DsTypography color="secondary" variant="body-sm-reg">
+						{variant}
+					</DsTypography>
+				</DsStack>
+			))}
+		</div>
+	),
+};

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

@@ -0,0 +1,29 @@
+import classNames from 'classnames';
+import styles from './ds-illustration.module.scss';
+import { illustrations } from './illustrations';
+import type { DsIllustrationProps } from './ds-illustration.types';
+
+const DsIllustration = ({
+	variant = 'no-tasks',
+	className,
+	style,
+	ref,
+	'aria-hidden': ariaHidden = true,
+	'aria-label': ariaLabel,
+}: DsIllustrationProps) => {
+	const Svg = illustrations[variant];
+
+	return (
+		<Svg
+			ref={ref}
+			className={classNames(styles.root, className)}
+			style={style}
+			aria-hidden={ariaHidden}
+			aria-label={ariaLabel}
+		/>
+	);
+};
+
+DsIllustration.displayName = 'DsIllustration';
+
+export default DsIllustration;

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

@@ -0,0 +1,45 @@
+import type { CSSProperties, Ref } from 'react';
+
+export const dsIllustrationVariants = [
+	'configuration',
+	'device',
+	'done',
+	'empty-inbox',
+	'error',
+	'go-filter',
+	'no-connection',
+	'no-credit-card',
+	'no-device',
+	'no-documents',
+	'no-gps',
+	'no-images',
+	'no-items-cart',
+	'no-messages',
+	'no-search-result',
+	'no-tasks',
+	'site',
+] as const;
+
+export type DsIllustrationVariant = (typeof dsIllustrationVariants)[number];
+
+export interface DsIllustrationProps {
+	/**
+	 * Which empty-screen tile to render.
+	 * @default 'no-tasks'
+	 */
+	variant?: DsIllustrationVariant;
+
+	className?: string;
+
+	style?: CSSProperties;
+
+	ref?: Ref<SVGSVGElement>;
+
+	/**
+	 * Decorative by default. Set `false` with `aria-label` when the tile is informative.
+	 * @default true
+	 */
+	'aria-hidden'?: boolean | 'true' | 'false';
+
+	'aria-label'?: string;
+}

packages/design-system/src/components/ds-illustration/illustrations/configuration.tsx

@@ -0,0 +1,51 @@
+import type { FC, SVGProps } from 'react';
+import { IllustrationClouds } from './illustration-clouds';
+
+export const ConfigurationIllustration: FC<SVGProps<SVGSVGElement>> = (props) => (
+	<svg
+		width="250"
+		height="200"
+		viewBox="0 0 250 200"
+		fill="none"
+		xmlns="http://www.w3.org/2000/svg"
+		{...props}
+	>
+		<rect width="250" height="200" fill="var(--background)" />
+		<IllustrationClouds />
+		<path
+			d="M140.238 48.25C140.621 48.2501 140.937 48.5362 140.982 48.9062L140.987 48.9482L140.995 48.9912L142.683 57.7295L142.821 58.4473L143.515 58.6777C144.17 58.8963 144.82 59.1328 145.466 59.3857L146.11 59.6445C146.961 59.9964 147.798 60.3775 148.622 60.7949L149.278 61.127L149.888 60.7148L157.375 55.6494C157.688 55.4384 158.104 55.495 158.351 55.7715L158.375 55.7998L158.401 55.8252L170.512 67.9355C170.777 68.2026 170.8 68.6213 170.579 68.9121L170.559 68.9395L170.539 68.9678L165.535 76.3623L165.124 76.9688L165.453 77.624C165.866 78.4456 166.252 79.2849 166.603 80.1338L166.604 80.1357C166.955 80.9829 167.28 81.8519 167.57 82.7344L167.8 83.4316L168.521 83.5713L177.393 85.2822H177.394C177.749 85.3506 178 85.6645 178 86.0156L178.004 103.253C178.004 103.636 177.718 103.952 177.348 103.997L177.306 104.002L177.263 104.01L168.521 105.697L167.8 105.837L167.57 106.534C167.284 107.404 166.959 108.269 166.606 109.123L166.604 109.128C166.259 109.972 165.874 110.807 165.457 111.638L165.128 112.292L165.539 112.898L170.603 120.383V120.384C170.782 120.651 170.769 120.989 170.598 121.234L170.515 121.334L158.323 133.525C158.058 133.791 157.64 133.815 157.349 133.599L157.326 133.581L157.303 133.565L149.889 128.546L149.281 128.135L148.626 128.464C147.796 128.881 146.957 129.267 146.119 129.614H146.118C145.273 129.965 144.408 130.286 143.523 130.577L142.826 130.807L142.687 131.528L140.976 140.399V140.4C140.907 140.755 140.594 141.007 140.242 141.007L123.004 141.011L122.864 140.998C122.547 140.938 122.301 140.679 122.261 140.352L122.255 140.309L122.247 140.267L120.563 131.528L120.425 130.807L119.727 130.577C118.853 130.29 117.992 129.968 117.152 129.62L117.055 129.577L117.029 129.567L116.419 129.307C115.811 129.041 115.211 128.758 114.62 128.458L113.963 128.125L113.354 128.538L105.873 133.604L105.872 133.605C105.576 133.806 105.181 133.763 104.936 133.515L104.931 133.51L92.7432 121.326L92.7383 121.321L92.6543 121.222C92.4826 120.976 92.4752 120.639 92.6494 120.38L97.7148 112.895L98.126 112.288L97.7969 111.633C97.3842 110.811 96.9983 109.972 96.6475 109.123L96.6465 109.121C96.2943 108.273 95.9697 107.408 95.6797 106.526L95.4502 105.829L94.7295 105.689L85.8623 103.979H85.8604C85.5057 103.91 85.254 103.597 85.2539 103.245L85.25 86.0068L85.2627 85.8672C85.3222 85.5505 85.581 85.3038 85.9092 85.2637L85.9521 85.2578L85.9941 85.25L94.7324 83.5664L95.4531 83.4277L95.6826 82.7314C95.9734 81.8517 96.2992 80.9802 96.6484 80.1299L96.6475 80.1289C96.9934 79.2907 97.3796 78.4579 97.7998 77.625L98.1309 76.9688L97.7188 76.3604L92.6523 68.876C92.4415 68.5611 92.502 68.1441 92.7734 67.9043L92.8018 67.8789L92.8291 67.8516L104.934 55.7422C105.199 55.4772 105.617 55.4527 105.909 55.6699L105.932 55.6865L105.955 55.7021L113.365 60.7178L113.973 61.1299L114.629 60.7988C115.457 60.381 116.286 59.9975 117.123 59.6533L117.214 59.6191L117.228 59.6143L117.24 59.6084C118.062 59.2715 118.898 58.9606 119.738 58.6807L120.432 58.4502L120.57 57.7324L122.281 48.8652V48.8633C122.349 48.5088 122.663 48.257 123.015 48.2568V48.2529L140.238 48.25Z"
+			fill="var(--background)"
+			stroke="var(--color-dap-blue-700)"
+			strokeWidth="2.5"
+		/>
+		<path
+			fillRule="evenodd"
+			clipRule="evenodd"
+			d="M154.29 112.995C155.197 111.885 156.012 110.723 156.736 109.521C158.327 106.877 159.474 104.036 160.175 101.107C160.883 98.1449 161.136 95.0927 160.931 92.0628C160.752 89.4188 160.224 86.7918 159.347 84.2564C158.476 81.741 157.262 79.3156 155.701 77.0533C154.772 75.7052 153.719 74.4149 152.544 73.198C150.818 71.4113 148.925 69.8838 146.914 68.6165C144.753 67.2549 142.456 66.1935 140.082 65.4337C137.11 64.4822 134.018 64.0035 130.926 64C128.519 63.9973 126.113 64.2823 123.762 64.856C121.116 65.5018 118.54 66.5137 116.115 67.893C113.983 69.1055 111.968 70.602 110.123 72.3835C107.804 74.6223 105.926 77.146 104.49 79.8469C103.084 82.4912 102.102 85.3053 101.546 88.1883C100.972 91.1584 100.85 94.2016 101.182 97.2072C101.612 101.103 102.803 104.935 104.759 108.464C106.011 110.722 107.577 112.856 109.456 114.802C112.44 117.892 115.924 120.206 119.655 121.741C124.193 123.607 129.096 124.319 133.912 123.869C137.953 123.492 141.933 122.296 145.583 120.276"
+			fill="var(--background)"
+		/>
+		<path
+			d="M154.29 112.995C155.197 111.885 156.012 110.723 156.736 109.521C158.327 106.877 159.474 104.036 160.175 101.107C160.883 98.1449 161.136 95.0927 160.931 92.0628C160.752 89.4188 160.224 86.7918 159.347 84.2564C158.476 81.741 157.262 79.3156 155.701 77.0533C154.772 75.7052 153.719 74.4149 152.544 73.198C150.818 71.4113 148.925 69.8838 146.914 68.6165C144.753 67.2549 142.456 66.1935 140.082 65.4337C137.11 64.4822 134.018 64.0035 130.926 64C128.519 63.9973 126.113 64.2823 123.762 64.856C121.116 65.5018 118.54 66.5137 116.115 67.893C113.983 69.1055 111.968 70.602 110.123 72.3835C107.804 74.6223 105.926 77.146 104.49 79.8469C103.084 82.4912 102.102 85.3053 101.546 88.1883C100.972 91.1584 100.85 94.2016 101.182 97.2072C101.612 101.103 102.803 104.935 104.759 108.464C106.011 110.722 107.577 112.856 109.456 114.802C112.44 117.892 115.924 120.206 119.655 121.741C124.193 123.607 129.096 124.319 133.912 123.869C137.953 123.492 141.933 122.296 145.583 120.276"
+			stroke="var(--color-dap-blue-700)"
+			strokeWidth="2.5"
+			strokeLinecap="round"
+			strokeLinejoin="round"
+		/>
+		<path
+			d="M157 95.62C156.823 95.6232 156.645 95.6248 156.468 95.6248C140.834 95.6248 128.034 83.4367 126.961 68C114.518 69.9628 105 80.7849 105 93.8412C105 108.288 116.654 120 131.03 120C144.81 120 156.09 109.238 157 95.62Z"
+			fill="var(--color-dap-blue-075)"
+		/>
+		<path
+			d="M124.755 71.4868C123.483 71.9639 122.24 72.5437 121.04 73.2264C119.175 74.2873 117.412 75.5966 115.798 77.1553C115.136 77.7943 114.515 78.4597 113.936 79.1485"
+			stroke="var(--color-dap-blue-400)"
+			strokeWidth="2.5"
+			strokeLinecap="round"
+		/>
+		<path
+			d="M111.142 82.5464C110.682 83.2428 110.258 83.9568 109.87 84.6854C109.584 85.2236 109.318 85.7698 109.072 86.3229"
+			stroke="var(--color-dap-blue-400)"
+			strokeWidth="2.5"
+			strokeLinecap="round"
+		/>
+	</svg>
+);