feat(design-system): rename DsWorkspace to DsWorkspaceLayout [AR-65647]

Author: mmurawski-dn

.changeset/ice-banana-dance.md

@@ -0,0 +1,6 @@
+---
+'@drivenets/design-system': minor
+---
+
+Add extended layout compound parts to `DsWorkspace` (`Body`, `SideMenu`, `LeftPanel`). `Content` now always applies content-area spacing — visual change for existing simple-shell consumers, API unchanged.
+Rename `DsWorkspace` to `DsWorkspaceLayout`.

CONTEXT.md

@@ -48,6 +48,34 @@ _Avoid_: replacement, v2 component (as a synonym for the pattern name)
 A **Component** (or prop type) still exported but documented as superseded; Storybook uses the `deprecated` tag.
 _Avoid_: legacy, old (without linking to the successor)
 
+**Workspace page**:
+A full-screen DAP route for a multi-step **Project** (create, view, or approve) with persistent header chrome and a structured body.
+_Avoid_: project page, wizard page, fullscreen layout (generic)
+
+**Workspace layout mode**:
+Either the simple shell (`Header`, optional `SubHeader`, `Content`, optional `Footer`) or the extended shell that swaps root `Content` for `Body` plus optional `SideMenu`, `LeftPanel`, and `Content` nested inside `Body`. Extended regions are opt-in; root-level `Content` keeps the simple shell default and must not change behavior for existing consumers.
+_Avoid_: layout prop, variant enum on the root component
+
+**Workspace body**:
+The region below the workspace header: optional top/bottom stepper bands plus a horizontal band for navigation chrome and main work area.
+_Avoid_: content (when meaning the whole page), main
+
+**Side menu panel** (workspace):
+Optional workspace-body chrome: vertical section navigation (collapsed rail, hover expand, optional pin) beside the work area; does not set **Content area** horizontal margins.
+_Avoid_: left nav, sidebar, catalog side menu (different page type)
+
+**Left side panel** (workspace):
+Optional docked panel in the workspace body that consumes width and pushes the **Content area** aside; when present, **Content area** uses 24px horizontal margins.
+_Avoid_: drawer, right side panel, side menu panel
+
+**Content area** (workspace):
+The primary work column (`DsWorkspace.Content`): column layout with 24px vertical margins, 16px gap, and 40px horizontal margins (24px when a **Left side panel** is present). Layout chrome only — title line and content items are consumer markup inside the slot. `SideMenu` does not affect horizontal margins.
+_Avoid_: main content, body, canvas (canvas is one kind of content)
+
+**Right side panel** (workspace):
+Optional drawer overlay scoped to the **Content area** only — workspace header and body chrome (side menu, left panel) stay visible; composed with `DsDrawer` inside **Content area**, not a push layout region.
+_Avoid_: left side panel, side menu panel, modal, body-wide overlay (unless product explicitly requires it)
+
 ## Relationships
 
 - A **Component** exposes **Variants** and may accept **Locale** when it shows built-in user-facing text
@@ -56,6 +84,10 @@ _Avoid_: legacy, old (without linking to the successor)
 - A **Successor component** supersedes a **Deprecated component**; both may ship until consumers migrate
 - **Tokens** flow from design into SCSS; **Components** consume tokens, not raw hex from Figma in new work
 - **Changesets** attach to package releases; a new **Component** or breaking API change typically needs one
+- A **Workspace page** has one header and one **Workspace body**; the body may combine **Side menu panel**, **Left side panel**, **Content area**, and **Right side panel**
+- **Side menu panel** and **Left side panel** differ: only **Left side panel** toggles **Content area** horizontal margins (24px vs 40px)
+- **Left side panel** pushes layout; **Right side panel** overlays **Content area** via `DsDrawer` (no symmetric right layout slot)
+- **Workspace layout mode** is opt-in: `Body` with `SideMenu` / `LeftPanel` adds horizontal chrome; `Content` always applies content-area spacing
 
 ## Example dialogue
 
@@ -65,6 +97,12 @@ _Avoid_: legacy, old (without linking to the successor)
 > **Dev:** "We're shipping `DsButtonV3` but `DsButton` is still exported."
 > **Domain expert:** "That's a **Successor component**. Leave `DsButton` as **Deprecated component** with `@deprecated` JSDoc until product apps migrate; new internal usage should import **Successor** only."
 
+> **Dev:** "Should the comments drawer cover the side menu?"
+> **Domain expert:** "No — **Right side panel** overlays **Content area** only. Header and body chrome stay visible; use `DsDrawer` inside **Content area**, not a full-body overlay."
+
+> **Dev:** "Should we add `ContentTitle` and `ContentItems` slots?"
+> **Domain expert:** "No — **Content area** is `Content`. Workspace exposes layout regions; page content (title line, content items) stays in consumer children."
+
 ## Flagged ambiguities
 
 - "Adapter" in file-upload vs "adapter" in generic architecture docs — resolved: use **Upload adapter** in design-system context; architecture skill uses **Adapter** at a **seam** ([LANGUAGE.md](.agents/skills/improve-codebase-architecture/LANGUAGE.md)).

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

@@ -1,4 +1,5 @@
-import { describe, expect, it } from 'vitest';
+import { Component, type ReactNode } from 'react';
+import { describe, expect, it, vi } from 'vitest';
 import { page } from 'vitest/browser';
 
 import DsWorkspace from '../ds-workspace';
@@ -187,4 +188,217 @@ describe('DsWorkspace', () => {
 		expect(dialogRect.top).toBeGreaterThanOrEqual(headerRect.bottom);
 		expect(dialogRect.bottom).toBeLessThanOrEqual(footerRect.top + 1);
 	});
+
+	it('applies content-area layout on Content', async () => {
+		await page.render(
+			<DsWorkspace fillParent>
+				<DsWorkspace.Content data-testid="content">
+					<span>Content area</span>
+				</DsWorkspace.Content>
+			</DsWorkspace>,
+		);
+
+		const content = page.getByTestId('content').element();
+		const style = getComputedStyle(content);
+
+		expect(content.className).not.toMatch(/contentWithLeftPanel/);
+		expect(style.flexDirection).toBe('column');
+		expect(style.paddingLeft).toBe('40px');
+		expect(style.paddingRight).toBe('40px');
+		expect(style.paddingTop).toBe('24px');
+		expect(style.paddingBottom).toBe('24px');
+		expect(style.gap).toBe('16px');
+	});
+
+	describe('extended shell', () => {
+		it('applies content-area margins when Body contains only Content', async () => {
+			await page.render(
+				<DsWorkspace fillParent>
+					<DsWorkspace.Body>
+						<DsWorkspace.Content data-testid="content">
+							<span>Content area</span>
+						</DsWorkspace.Content>
+					</DsWorkspace.Body>
+				</DsWorkspace>,
+			);
+
+			const content = page.getByTestId('content').element();
+			const style = getComputedStyle(content);
+
+			expect(content.className).not.toMatch(/contentWithLeftPanel/);
+			expect(style.paddingLeft).toBe('40px');
+			expect(style.paddingRight).toBe('40px');
+			expect(style.paddingTop).toBe('24px');
+			expect(style.paddingBottom).toBe('24px');
+			expect(style.gap).toBe('16px');
+		});
+
+		it('applies reduced horizontal margins when LeftPanel is mounted', async () => {
+			await page.render(
+				<DsWorkspace fillParent>
+					<DsWorkspace.Body>
+						<DsWorkspace.LeftPanel>
+							<span>Left panel</span>
+						</DsWorkspace.LeftPanel>
+						<DsWorkspace.Content data-testid="content">
+							<span>Content area</span>
+						</DsWorkspace.Content>
+					</DsWorkspace.Body>
+				</DsWorkspace>,
+			);
+
+			const content = page.getByTestId('content').element();
+			const style = getComputedStyle(content);
+
+			expect(content.className).toMatch(/contentWithLeftPanel/);
+			expect(style.paddingLeft).toBe('24px');
+			expect(style.paddingRight).toBe('24px');
+		});
+
+		it('toggles Content margin class when LeftPanel is mounted and unmounted', async () => {
+			const WorkspaceWithOptionalLeftPanel = ({ showLeftPanel }: { showLeftPanel: boolean }) => (
+				<DsWorkspace fillParent>
+					<DsWorkspace.Body>
+						{showLeftPanel ? (
+							<DsWorkspace.LeftPanel>
+								<span>Left panel</span>
+							</DsWorkspace.LeftPanel>
+						) : null}
+						<DsWorkspace.Content data-testid="content">
+							<span>Content area</span>
+						</DsWorkspace.Content>
+					</DsWorkspace.Body>
+				</DsWorkspace>
+			);
+
+			const { rerender } = await page.render(<WorkspaceWithOptionalLeftPanel showLeftPanel={false} />);
+
+			let content = page.getByTestId('content').element();
+			expect(content.className).not.toMatch(/contentWithLeftPanel/);
+			expect(getComputedStyle(content).paddingLeft).toBe('40px');
+
+			await rerender(<WorkspaceWithOptionalLeftPanel showLeftPanel={true} />);
+
+			content = page.getByTestId('content').element();
+			expect(content.className).toMatch(/contentWithLeftPanel/);
+			expect(getComputedStyle(content).paddingLeft).toBe('24px');
+
+			await rerender(<WorkspaceWithOptionalLeftPanel showLeftPanel={false} />);
+
+			content = page.getByTestId('content').element();
+			expect(content.className).not.toMatch(/contentWithLeftPanel/);
+			expect(getComputedStyle(content).paddingLeft).toBe('40px');
+		});
+
+		it('does not change Content horizontal margins when SideMenu is present', async () => {
+			await page.render(
+				<DsWorkspace fillParent>
+					<DsWorkspace.Body>
+						<DsWorkspace.SideMenu>
+							<span>Nav</span>
+						</DsWorkspace.SideMenu>
+						<DsWorkspace.Content data-testid="content">
+							<span>Content area</span>
+						</DsWorkspace.Content>
+					</DsWorkspace.Body>
+				</DsWorkspace>,
+			);
+
+			const content = page.getByTestId('content').element();
+			const style = getComputedStyle(content);
+
+			expect(content.className).not.toMatch(/contentWithLeftPanel/);
+			expect(style.paddingLeft).toBe('40px');
+			expect(style.paddingRight).toBe('40px');
+		});
+
+		it('content in Body creates a stacking context for drawer containment', async () => {
+			await page.render(
+				<DsWorkspace fillParent>
+					<DsWorkspace.Body>
+						<DsWorkspace.Content data-testid="content">
+							<span>Content area</span>
+						</DsWorkspace.Content>
+					</DsWorkspace.Body>
+				</DsWorkspace>,
+			);
+
+			const contentEl = page.getByTestId('content').element();
+			const style = getComputedStyle(contentEl);
+
+			expect(style.position).toBe('relative');
+		});
+
+		it('drawer inside Body Content is positioned below header', async () => {
+			await page.render(
+				<div style={{ height: 500 }}>
+					<DsWorkspace fillParent>
+						<DsWorkspace.Header>
+							<span>Header</span>
+						</DsWorkspace.Header>
+						<DsWorkspace.Body>
+							<DsWorkspace.Content>
+								<div style={{ position: 'absolute', inset: 0 }} role="dialog" aria-label="Drawer">
+									Drawer
+								</div>
+								<span>Main area</span>
+							</DsWorkspace.Content>
+						</DsWorkspace.Body>
+						<DsWorkspace.Footer>
+							<span>Footer</span>
+						</DsWorkspace.Footer>
+					</DsWorkspace>
+				</div>,
+			);
+
+			const headerRect = page.getByRole('banner').element().getBoundingClientRect();
+			const dialogRect = page.getByRole('dialog').element().getBoundingClientRect();
+			const footerRect = page.getByRole('contentinfo').element().getBoundingClientRect();
+
+			expect(dialogRect.top).toBeGreaterThanOrEqual(headerRect.bottom);
+			expect(dialogRect.bottom).toBeLessThanOrEqual(footerRect.top + 1);
+		});
+
+		it('throws when extended compound parts are used outside DsWorkspace', async () => {
+			class TestErrorBoundary extends Component<
+				{ children: ReactNode; onError: (error: Error) => void },
+				{ error: Error | null }
+			> {
+				override state = { error: null as Error | null };
+
+				static getDerivedStateFromError(error: Error) {
+					return { error };
+				}
+
+				override componentDidCatch(error: Error) {
+					this.props.onError(error);
+				}
+
+				override render() {
+					if (this.state.error) {
+						return null;
+					}
+
+					return this.props.children;
+				}
+			}
+
+			const onError = vi.fn<(error: Error) => void>();
+
+			await page.render(
+				<TestErrorBoundary onError={onError}>
+					<DsWorkspace.Body>
+						<DsWorkspace.Content>
+							<span>Content only</span>
+						</DsWorkspace.Content>
+					</DsWorkspace.Body>
+				</TestErrorBoundary>,
+			);
+
+			expect(onError).toHaveBeenCalledOnce();
+			expect(onError.mock.calls[0]?.[0]?.message).toBe(
+				'DsWorkspace compound components must be used within DsWorkspace',
+			);
+		});
+	});
 });

packages/design-system/src/components/ds-workspace/ds-workspace.context.ts

@@ -0,0 +1,19 @@
+import { createContext, useContext } from 'react';
+
+export interface DsWorkspaceContextValue {
+	hasLeftSidePanel: boolean;
+	registerLeftSidePanel: () => void;
+	unregisterLeftSidePanel: () => void;
+}
+
+export const DsWorkspaceContext = createContext<DsWorkspaceContextValue | null>(null);
+
+export const useDsWorkspaceContext = () => {
+	const context = useContext(DsWorkspaceContext);
+
+	if (!context) {
+		throw new Error('DsWorkspace compound components must be used within DsWorkspace');
+	}
+
+	return context;
+};