@umituz/web-dashboard 6.6.1 → 6.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/web-dashboard",
-  "version": "6.6.1",
+  "version": "6.8.0",
   "description": "Installable app skeleton for the fleet — layouts, analytics (dependency-free SVG charts), calendar, onboarding flow, i18n via @umituz/web-localization, permissions/module registry; udb-* stylesheet on design-system tokens",
   "type": "module",
   "main": "./src/index.ts",
@@ -66,7 +66,7 @@
     }
   },
   "dependencies": {
-    "@umituz/web-design-system": "^4.18.0",
+    "@umituz/web-design-system": "^4.19.0",
     "lucide-react": "^0.577.0",
     "@umituz/web-localization": "^1.2.1"
   },

package/src/domains/layouts/components/DashboardLayout.test.tsx

@@ -0,0 +1,101 @@
+import { describe, expect, it, vi } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { MemoryRouter, Routes, Route } from "react-router-dom";
+import { Home } from "lucide-react";
+import { DashboardLayout } from "./DashboardLayout";
+import type { DashboardLayoutConfig } from "../types/layout";
+
+const config: DashboardLayoutConfig = {
+  sidebarGroups: [
+    {
+      title: "Main",
+      items: [{ path: "/", label: "Home", icon: Home, end: false }],
+    },
+  ],
+  brandName: "Test",
+  defaultTitle: "Workspace",
+};
+
+function renderAt(path: string, mainId?: string, configOverride?: DashboardLayoutConfig) {
+  return render(
+    <MemoryRouter initialEntries={[path]}>
+      <Routes>
+        <Route
+          path="*"
+          element={
+            <DashboardLayout config={configOverride ?? config} mainId={mainId}>
+              {/* children are ignored — the layout renders an Outlet */}
+            </DashboardLayout>
+          }
+        >
+          <Route path="*" element={<div>outlet-content</div>} />
+        </Route>
+      </Routes>
+    </MemoryRouter>
+  );
+}
+
+describe("DashboardLayout (shell a11y)", () => {
+  it("renders a skip link targeting the main landmark", () => {
+    renderAt("/");
+    const skip = screen.getByRole("link", { name: /skip to content/i });
+    expect(skip.getAttribute("href")).toBe("#udb-main");
+    expect(document.getElementById("udb-main")).not.toBeNull();
+  });
+
+  it("honours a custom mainId on both the link and the landmark", () => {
+    renderAt("/", "main-content");
+    expect(screen.getByRole("link", { name: /skip to content/i }).getAttribute("href")).toBe("#main-content");
+    expect(document.getElementById("main-content")).not.toBeNull();
+  });
+
+  it("renders the routed outlet inside the main landmark", () => {
+    renderAt("/");
+    const main = document.getElementById("udb-main");
+    expect(main?.textContent).toContain("outlet-content");
+  });
+});
+
+describe("DashboardLayout (command palette)", () => {
+  const paletteConfig = (extra?: Partial<DashboardLayoutConfig>): DashboardLayoutConfig => ({
+    ...config,
+    commandPalette: {
+      groups: [{ heading: "Go to", items: [{ id: "home", label: "Home", onSelect: () => {} }] }],
+      placeholder: "Search commands…",
+    },
+    ...extra,
+  });
+
+  it("renders the palette's search button in the header and opens it on click", async () => {
+    renderAt("/", undefined, paletteConfig());
+    fireEvent.click(screen.getByRole("button", { name: /search commands/i }));
+    expect(await screen.findByRole("dialog")).toBeTruthy();
+    expect(await screen.findByRole("option", { name: "Home" })).toBeTruthy();
+  });
+
+  it("toggles the palette with ⌘K / Ctrl+K", async () => {
+    renderAt("/", undefined, paletteConfig());
+    expect(screen.queryByRole("dialog")).toBeNull();
+    fireEvent.keyDown(window, { key: "k", metaKey: true });
+    expect(await screen.findByRole("dialog")).toBeTruthy();
+    fireEvent.keyDown(window, { key: "k", metaKey: true });
+    expect(screen.queryByRole("dialog")).toBeNull();
+  });
+
+  it("does not bind the shortcut when shortcut: false", () => {
+    renderAt("/", undefined, {
+      ...config,
+      commandPalette: { groups: [], shortcut: false },
+    });
+    fireEvent.keyDown(window, { key: "k", ctrlKey: true });
+    expect(screen.queryByRole("dialog")).toBeNull();
+  });
+
+  it("keeps an explicit searchAction.onActivate over the palette takeover", () => {
+    const onActivate = vi.fn();
+    renderAt("/", undefined, paletteConfig({ searchAction: { placeholder: "Go search", onActivate } }));
+    fireEvent.click(screen.getByRole("button", { name: /go search/i }));
+    expect(onActivate).toHaveBeenCalledTimes(1);
+    expect(screen.queryByRole("dialog")).toBeNull();
+  });
+});

package/src/domains/layouts/components/DashboardLayout.tsx

@@ -2,8 +2,10 @@ import { useState, useEffect, type ReactNode } from "react";
 import { useLocation, Outlet, Navigate } from "react-router-dom";
 import { useT } from "@umituz/web-localization/react";
 import { Skeleton } from "@umituz/web-design-system/atoms";
+import { CommandPalette } from "@umituz/web-design-system/organisms";
 import { DashboardSidebar } from "./DashboardSidebar";
 import { DashboardHeader } from "./DashboardHeader";
+import { getActiveSidebarItem } from "../utils/dashboard";
 import type { DashboardLayoutConfig } from "../types/layout";
 import type { DashboardNotification } from "../types/notification";
 import type { DashboardUser } from "../types/user";
@@ -25,6 +27,10 @@ interface DashboardLayoutProps {
   collapsedStorageKey?: string;
   /** Optional page footer rendered under the outlet column. */
   footer?: ReactNode;
+  /** id of the main landmark — also the skip-link target. */
+  mainId?: string;
+  /** Skip-link label (a11y); defaults to the localized "Skip to content". */
+  skipToContentLabel?: string;
 }
 
 const readCollapsed = (key?: string): boolean => {
@@ -51,12 +57,16 @@ export const DashboardLayout = ({
   routeTransitionMs = 0,
   collapsedStorageKey,
   footer,
+  mainId = "udb-main",
+  skipToContentLabel,
 }: DashboardLayoutProps) => {
   const location = useLocation();
   const t = useT();
   const [collapsed, setCollapsed] = useState(() => readCollapsed(collapsedStorageKey));
   const [mobileOpen, setMobileOpen] = useState(false);
   const [loading, setLoading] = useState(routeTransitionMs > 0);
+  const [paletteOpen, setPaletteOpen] = useState(false);
+  const palette = config.commandPalette;
 
   useEffect(() => {
     if (!collapsedStorageKey || typeof window === "undefined") return;
@@ -81,12 +91,37 @@ export const DashboardLayout = ({
     setMobileOpen(false);
   }, [location.pathname]);
 
+  useEffect(() => {
+    if (!palette || palette.shortcut === false) return;
+    const onKeyDown = (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === "k") {
+        e.preventDefault();
+        setPaletteOpen((v) => !v);
+      }
+    };
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [palette]);
+
+  useEffect(() => {
+    if (!mobileOpen) return;
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "Escape") setMobileOpen(false);
+    };
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [mobileOpen]);
+
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+    document.documentElement.classList.toggle("udb-scroll-lock", mobileOpen);
+    return () => document.documentElement.classList.remove("udb-scroll-lock");
+  }, [mobileOpen]);
+
   if (authLoading) return null;
   if (!isAuthenticated) return <Navigate to={loginRoute} replace />;
 
-  const activeItem = config.sidebarGroups
-    .flatMap((group) => group.items)
-    .find((i) => i.path === location.pathname);
+  const activeItem = getActiveSidebarItem(location.pathname, config.sidebarGroups);
 
   const getTitle = () => {
     if (activeItem) return activeItem.raw ? activeItem.label : t(activeItem.label);
@@ -109,6 +144,10 @@ export const DashboardLayout = ({
 
   return (
     <div className="udb-root udb-layout">
+      <a href={`#${mainId}`} className="udb-skip-link">
+        {skipToContentLabel ?? t("Skip to content")}
+      </a>
+
       <aside
         className={`udb-layout__sidebar ${collapsed ? "udb-layout__sidebar--collapsed" : ""}`}
       >
@@ -122,7 +161,12 @@ export const DashboardLayout = ({
       {mobileOpen && (
         <div className="udb-layout__mobile">
           <div className="udb-layout__backdrop" onClick={() => setMobileOpen(false)} />
-          <aside className="udb-layout__mobile-sidebar">
+          <aside
+            className="udb-layout__mobile-sidebar"
+            role="dialog"
+            aria-modal="true"
+            aria-label={config.brandName ? `${config.brandName} — ${t("Navigation")}` : t("Navigation")}
+          >
             <DashboardSidebar
               collapsed={false}
               setCollapsed={() => setMobileOpen(false)}
@@ -146,14 +190,19 @@ export const DashboardLayout = ({
           onMarkAllRead={onMarkAllRead}
           onDismissNotification={onDismissNotification}
           loginRoute={loginRoute}
-          searchAction={config.searchAction}
+          searchAction={
+            palette
+              ? // The palette owns the header search unless the app gave an explicit action.
+                { placeholder: palette.placeholder, shortcut: "⌘K", ...config.searchAction, onActivate: config.searchAction?.onActivate ?? (() => setPaletteOpen(true)) }
+              : config.searchAction
+          }
           headerExtra={config.headerExtra}
           profileItems={config.profileItems}
           showDefaultProfileItems={config.showDefaultProfileItems}
           notificationsViewAll={config.notificationsViewAll}
         />
 
-        <main className="udb-layout__content">
+        <main id={mainId} tabIndex={-1} className="udb-layout__content">
           {loading ? (
             <div className="udb-page-skeleton">
               <Skeleton className="udb-skeleton--title" />
@@ -171,6 +220,17 @@ export const DashboardLayout = ({
 
         {footer && <footer className="udb-layout__footer">{footer}</footer>}
       </div>
+
+      {palette && (
+        <CommandPalette
+          open={paletteOpen}
+          onOpenChange={setPaletteOpen}
+          groups={palette.groups}
+          placeholder={palette.placeholder}
+          emptyLabel={palette.emptyLabel}
+          label={palette.label}
+        />
+      )}
     </div>
   );
 };

package/src/domains/layouts/components/DashboardSidebar.tsx

@@ -5,6 +5,7 @@ import { useT } from "@umituz/web-localization/react";
 import { Button } from "@umituz/web-design-system/atoms";
 import { cn } from "@umituz/web-design-system/utils/cn";
 import { BrandLogo } from "./BrandLogo";
+import { isPathActive } from "../utils/dashboard";
 import { PenTool, Menu, ChevronLeft, ChevronDown, ChevronRight } from "lucide-react";
 import type { DashboardSidebarProps, SidebarAction } from "../types/layout";
 import type { DashboardUser } from "../types/user";
@@ -128,9 +129,7 @@ export const DashboardSidebar = ({
                 )}
 
                 {(!isGroupCollapsed || collapsed) && filteredItems.map((item) => {
-                  const active =
-                    location.pathname === item.path ||
-                    (item.end === false && location.pathname.startsWith(item.path + "/"));
+                  const active = isPathActive(location.pathname, item.path, item.end);
                   const labelText = item.raw ? item.label : t(item.label);
                   const collapsedTitle =
                     item.badge !== undefined && item.badge !== ""

package/src/domains/layouts/hooks/dashboard.ts

@@ -1,6 +1,25 @@
-import { useState, useCallback } from "react";
+import { useState, useCallback, useEffect } from "react";
 import type { DashboardNotification } from "../types/notification";
 
+export interface UsePageTitleOptions {
+  /** Appended as `title · suffix` (e.g. the product name). */
+  suffix?: string;
+  /** Used when the route passes no title (e.g. the home route). */
+  fallback?: string;
+}
+
+/** Document title per route — `usePageTitle("Search", { suffix: "Lingora" })`
+ *  → "Search · Lingora". Restores nothing on unmount (the next route sets it). */
+export function usePageTitle(title?: string, options: UsePageTitleOptions = {}) {
+  const { suffix, fallback } = options;
+
+  useEffect(() => {
+    if (title && suffix) document.title = `${title} · ${suffix}`;
+    else if (title) document.title = title;
+    else if (fallback) document.title = fallback;
+  }, [title, suffix, fallback]);
+}
+
 export function useNotifications(initialNotifications: DashboardNotification[] = []) {
   const [notifications, setNotifications] = useState<DashboardNotification[]>(initialNotifications);
 

package/src/domains/layouts/hooks/index.ts

@@ -1,4 +1,5 @@
 export {
+  usePageTitle,
   useNotifications,
   useSidebar,
 } from './dashboard';

package/src/domains/layouts/hooks/usePageTitle.test.tsx

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { render } from "@testing-library/react";
+import { usePageTitle } from "./dashboard";
+
+function Probe({ title, suffix, fallback }: { title?: string; suffix?: string; fallback?: string }) {
+  usePageTitle(title, { suffix, fallback });
+  return null;
+}
+
+describe("usePageTitle", () => {
+  it("sets `title · suffix` when both are given", () => {
+    document.title = "before";
+    render(<Probe title="Search" suffix="Lingora" />);
+    expect(document.title).toBe("Search · Lingora");
+  });
+
+  it("sets the bare title without a suffix", () => {
+    render(<Probe title="Search" />);
+    expect(document.title).toBe("Search");
+  });
+
+  it("falls back when the route passes no title", () => {
+    render(<Probe fallback="Lingora — English, examined properly" />);
+    expect(document.title).toBe("Lingora — English, examined properly");
+  });
+
+  it("leaves the previous title untouched with neither title nor fallback", () => {
+    document.title = "kept";
+    render(<Probe />);
+    expect(document.title).toBe("kept");
+  });
+});

package/src/domains/layouts/types/layout.ts

@@ -32,6 +32,18 @@ export interface HeaderSearchAction {
     onActivate: () => void;
 }
 
+/** ⌘K command palette wired into the shell: renders the DS CommandPalette,
+ *  binds ⌘K/Ctrl+K, and (unless searchAction overrides it) makes the header
+ *  search button open the palette. */
+export interface CommandPaletteConfig {
+    groups: import("@umituz/web-design-system/organisms").CommandGroup[];
+    placeholder?: string;
+    emptyLabel?: string;
+    label?: string;
+    /** Bind ⌘K/Ctrl+K to open the palette (default true). */
+    shortcut?: boolean;
+}
+
 export interface DashboardSidebarProps {
     collapsed: boolean;
     setCollapsed: (collapsed: boolean) => void;
@@ -51,6 +63,9 @@ export interface DashboardLayoutConfig {
     /** Extra node rendered in the header actions area (app chips, clocks…). */
     headerExtra?: React.ReactNode;
     searchAction?: HeaderSearchAction;
+    /** ⌘K palette — when set, the header search opens it (an explicit
+     *  searchAction.onActivate still wins). */
+    commandPalette?: CommandPaletteConfig;
     /** Fully custom profile menu items — shown in addition to (or, with showDefaultProfileItems=false, instead of) the defaults. */
     profileItems?: HeaderProfileItem[];
     /** Hide the built-in profile/settings items (defaults to true). */

package/src/domains/layouts/utils/dashboard.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "vitest";
+import { getActiveSidebarItem, getPageTitle, isPathActive } from "./dashboard";
+
+describe("isPathActive", () => {
+  it("matches exact paths regardless of end", () => {
+    expect(isPathActive("/app/courses", "/app/courses")).toBe(true);
+    expect(isPathActive("/app/courses", "/app/courses", false)).toBe(true);
+  });
+
+  it("does not match siblings or parents by default (end defaults to true)", () => {
+    expect(isPathActive("/app/courses/lesson-1", "/app/courses")).toBe(false);
+    expect(isPathActive("/application", "/app")).toBe(false);
+  });
+
+  it("matches child routes when end is false", () => {
+    expect(isPathActive("/app/courses/lesson-1", "/app/courses", false)).toBe(true);
+    expect(isPathActive("/app", "/app", false)).toBe(true);
+  });
+
+  it("prefix match never crosses a path segment boundary", () => {
+    expect(isPathActive("/application", "/app", false)).toBe(false);
+    expect(isPathActive("/app/extra", "/app", false)).toBe(true);
+  });
+});
+
+describe("getPageTitle", () => {
+  const groups = [
+    {
+      items: [
+        { path: "/app", label: "Workspace", end: false },
+        { path: "/app/courses", label: "Courses" },
+      ],
+    },
+  ];
+
+  it("resolves the exact item first", () => {
+    expect(getPageTitle("/app/courses", groups)).toBe("Courses");
+  });
+
+  it("resolves prefix items on child routes (end: false)", () => {
+    expect(getPageTitle("/app/planner", groups)).toBe("Workspace");
+  });
+
+  it("falls back to the extra title map, then null", () => {
+    expect(getPageTitle("/x", groups, { "/x": "Extra" })).toBe("Extra");
+    expect(getPageTitle("/x", groups)).toBeNull();
+  });
+
+  it("prefers the longest prefix parent when several match", () => {
+    const nested = [
+      {
+        items: [
+          { path: "/app", label: "Workspace", end: false },
+          { path: "/app/courses", label: "Courses", end: false },
+          { path: "/app/courses/lesson-1", label: "Lesson" },
+        ],
+      },
+    ];
+    // An exact item always wins over prefix parents…
+    expect(getPageTitle("/app/courses/lesson-1", nested)).toBe("Lesson");
+    // …on deeper routes the longest prefix parent wins.
+    expect(getPageTitle("/app/courses/lesson-1/summary", nested)).toBe("Courses");
+    expect(getActiveSidebarItem("/nowhere", nested)).toBeNull();
+  });
+});

package/src/domains/layouts/utils/dashboard.ts

@@ -11,21 +11,50 @@ export function formatNotificationTime(
   return t("dashboard.activityFeed.times.daysAgo", { val: Math.floor(secs / 86400) });
 }
 
-export function isPathActive(currentPath: string, targetPath: string): boolean {
-  return currentPath === targetPath;
+/** Exact match by default; `end: false` also matches the path's children
+ *  (`/app/courses` stays active on `/app/courses/lesson-1`). */
+export function isPathActive(currentPath: string, targetPath: string, end = true): boolean {
+  return currentPath === targetPath || (!end && currentPath.startsWith(targetPath + "/"));
+}
+
+export interface TitledPath {
+  path: string;
+  label: string;
+  end?: boolean;
+}
+
+/** Most specific active item: an exact match always wins, otherwise the
+ *  longest `end: false` prefix parent (`/app/courses` beats `/app` on
+ *  `/app/courses/lesson-1`). */
+export function getActiveSidebarItem<T extends TitledPath>(
+  pathname: string,
+  sidebarGroups: Array<{ items: T[] }>
+): T | null {
+  let best: T | null = null;
+  for (const group of sidebarGroups) {
+    for (const item of group.items) {
+      if (pathname === item.path) return item;
+      if (
+        item.end === false &&
+        pathname.startsWith(item.path + "/") &&
+        (!best || item.path.length > best.path.length)
+      ) {
+        best = item;
+      }
+    }
+  }
+  return best;
 }
 
 export function getPageTitle(
   pathname: string,
-  sidebarGroups: Array<{ items: Array<{ path: string; label: string }> }>,
+  sidebarGroups: Array<{ items: TitledPath[] }>,
   extraTitleMap?: Record<string, string>
 ): string | null {
-    for (const group of sidebarGroups) {
-    const item = group.items.find((i) => i.path === pathname);
-    if (item) return item.label;
-  }
+  const item = getActiveSidebarItem(pathname, sidebarGroups);
+  if (item) return item.label;
 
-    if (extraTitleMap?.[pathname]) {
+  if (extraTitleMap?.[pathname]) {
     return extraTitleMap[pathname];
   }
 
@@ -37,9 +66,9 @@ export function filterSidebarItems<T extends { enabled?: boolean; requiredApp?:
   user?: { hasMobileApp?: boolean; hasWebApp?: boolean }
 ): T[] {
   return items.filter((item) => {
-        if (item.enabled === false) return false;
+    if (item.enabled === false) return false;
 
-        if (!item.requiredApp) return true;
+    if (!item.requiredApp) return true;
     if (item.requiredApp === "mobile") return user?.hasMobileApp ?? false;
     if (item.requiredApp === "web") return user?.hasWebApp ?? false;
 

package/src/domains/layouts/utils/index.ts

@@ -1,6 +1,7 @@
 export {
   formatNotificationTime,
   isPathActive,
+  getActiveSidebarItem,
   getPageTitle,
   filterSidebarItems,
   generateNotificationId,

package/src/styles/chrome.css

@@ -529,6 +529,35 @@
   color: var(--color-muted-foreground);
   font-size: var(--udb-font-size-sm);
 }
+
+/* — Skip link: first focusable element, visible only when focused — */
+.udb-skip-link {
+  position: fixed;
+  top: var(--udb-space-2);
+  left: var(--udb-space-2);
+  z-index: 100;
+  transform: translateY(-200%);
+  padding: var(--udb-space-2) var(--udb-space-4);
+  border-radius: var(--radius-md);
+  background: var(--color-primary);
+  color: var(--color-primary-foreground);
+  font-size: var(--udb-font-size-sm);
+  font-weight: 500;
+  text-decoration: none;
+  transition: transform 0.1s ease;
+}
+.udb-skip-link:focus {
+  transform: translateY(0);
+}
+/* Programmatic focus (skip target) shows no ring — the jump itself is the cue. */
+.udb-layout__content:focus {
+  outline: none;
+}
+
+/* Scroll lock applied to <html> while the mobile drawer is open. */
+.udb-scroll-lock {
+  overflow: hidden;
+}
 .udb-filter-bar {
   display: flex;
   flex-wrap: wrap;