test: add RTL tests for DashboardLayout slot composition and landmarks

Closes #673

Adds composition coverage for the authenticated shell: children land in
main#main-content, header/sidebar slots render, skip-to-content targets
main, and empty children still keep chrome up. Documents the regions in
docs/dashboard-layout.md. Error-boundary isolation stays in the existing
DashboardLayout.error-boundary.test.tsx.

Author: shinZoxdz

components/shared/layout/DashboardLayout.test.tsx

@@ -0,0 +1,124 @@
+import React from "react";
+import { render, screen, within } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import DashboardLayout from "./DashboardLayout";
+
+vi.mock("./SideNav", () => ({
+  SideNav: () => (
+    <nav aria-label="Primary" data-testid="mock-sidenav">
+      SideNav
+    </nav>
+  ),
+}));
+
+vi.mock("@/components/shared/layout/TopNav", () => ({
+  default: () => <div data-testid="mock-topnav">TopNav</div>,
+}));
+
+describe("DashboardLayout — slot composition", () => {
+  it("renders children into the main content region", () => {
+    render(
+      <DashboardLayout>
+        <div data-testid="page-body">Markets page</div>
+      </DashboardLayout>,
+    );
+
+    const main = screen.getByRole("main");
+    expect(within(main).getByTestId("page-body")).toHaveTextContent(
+      "Markets page",
+    );
+  });
+
+  it("renders the header slot with TopNav", () => {
+    render(
+      <DashboardLayout>
+        <span>content</span>
+      </DashboardLayout>,
+    );
+
+    const header = screen.getByRole("banner");
+    expect(within(header).getByTestId("mock-topnav")).toBeInTheDocument();
+  });
+
+  it("renders the sidebar navigation slot", () => {
+    render(
+      <DashboardLayout>
+        <span>content</span>
+      </DashboardLayout>,
+    );
+
+    expect(screen.getByTestId("mock-sidenav")).toBeInTheDocument();
+    expect(
+      screen.getByRole("navigation", { name: "Primary" }),
+    ).toBeInTheDocument();
+  });
+
+  it("renders an empty main region when no children are provided", () => {
+    render(<DashboardLayout>{null}</DashboardLayout>);
+
+    const main = screen.getByRole("main");
+    expect(main).toBeInTheDocument();
+    expect(main).toBeEmptyDOMElement();
+  });
+
+  it("keeps chrome slots present when children are omitted", () => {
+    render(<DashboardLayout>{undefined}</DashboardLayout>);
+
+    expect(screen.getByTestId("mock-sidenav")).toBeInTheDocument();
+    expect(screen.getByTestId("mock-topnav")).toBeInTheDocument();
+    expect(screen.getByRole("main")).toBeInTheDocument();
+  });
+});
+
+describe("DashboardLayout — landmarks and skip link", () => {
+  it("exposes a main landmark with the skip-target id", () => {
+    render(
+      <DashboardLayout>
+        <p>body</p>
+      </DashboardLayout>,
+    );
+
+    const main = screen.getByRole("main");
+    expect(main).toHaveAttribute("id", "main-content");
+  });
+
+  it("renders a skip-to-content link that points at main", () => {
+    render(
+      <DashboardLayout>
+        <p>body</p>
+      </DashboardLayout>,
+    );
+
+    const skip = screen.getByRole("link", { name: /skip to main content/i });
+    expect(skip).toHaveAttribute("href", "#main-content");
+  });
+
+  it("places the skip link before the chrome so keyboard users reach it first", () => {
+    const { container } = render(
+      <DashboardLayout>
+        <p>body</p>
+      </DashboardLayout>,
+    );
+
+    const skip = screen.getByRole("link", { name: /skip to main content/i });
+    const sidenav = screen.getByTestId("mock-sidenav");
+    // Document order: skip link precedes the sidebar.
+    expect(
+      skip.compareDocumentPosition(sidenav) &
+        Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+    expect(container.firstElementChild?.contains(skip)).toBe(true);
+  });
+
+  it("composes header and main inside the primary column", () => {
+    render(
+      <DashboardLayout>
+        <div data-testid="page-body">body</div>
+      </DashboardLayout>,
+    );
+
+    const header = screen.getByRole("banner");
+    const main = screen.getByRole("main");
+    expect(header.compareDocumentPosition(main) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
+  });
+});

docs/dashboard-layout.md

@@ -0,0 +1,51 @@
+# DashboardLayout regions
+
+How the authenticated shell is composed.
+
+Source: [`components/shared/layout/DashboardLayout.tsx`](../components/shared/layout/DashboardLayout.tsx)
+
+Tests:
+
+- Composition / landmarks: [`DashboardLayout.test.tsx`](../components/shared/layout/DashboardLayout.test.tsx)
+- Error isolation: [`DashboardLayout.error-boundary.test.tsx`](../components/shared/layout/DashboardLayout.error-boundary.test.tsx)
+
+## Regions
+
+```
+┌──────────┬────────────────────────────┐
+│          │  header (TopNav)           │
+│ SideNav  ├────────────────────────────┤
+│ (nav)    │  main#main-content         │
+│          │    {children}              │
+└──────────┴────────────────────────────┘
+```
+
+| Region   | Element                         | Role / landmark        | Failure mode                          |
+| -------- | ------------------------------- | ---------------------- | ------------------------------------- |
+| Skip     | `<a href="#main-content">`      | link                   | Always present; `sr-only` until focus |
+| Sidebar  | `<SideNav />`                   | navigation (in SideNav)| `sidenav-fallback` via error boundary |
+| Header   | `<header><TopNav /></header>`   | banner                 | `topnav-fallback` via error boundary  |
+| Content  | `<main id="main-content">`      | main                   | Always mounts; children optional      |
+
+## Skip link
+
+The first focusable control is "Skip to main content". It targets
+`#main-content` so keyboard users bypass the sidebar and top nav.
+
+## Error isolation
+
+`SideNav` and `TopNav` each sit inside a `LayoutRegionBoundary`. If either
+throws during render the rest of the shell stays up — the main content region
+is never unmounted by a chrome failure. See the error-boundary tests.
+
+## Collapsed / expanded rail
+
+The layout shell itself does not own collapsed-rail state. Rail expansion is
+owned by `SideNav` / its context. Composition tests assert the sidebar *slot*
+is present; rail width behaviour is covered by SideNav's own suite.
+
+## Empty children
+
+`DashboardLayout` accepts any `ReactNode`. Passing `null` / `undefined` still
+renders the chrome and an empty `<main>` — useful for loading routes that
+suspend their body.