@umituz/web-dashboard 6.7.0 → 6.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/web-dashboard",
-  "version": "6.7.0",
+  "version": "6.9.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

@@ -1,5 +1,5 @@
-import { describe, expect, it } from "vitest";
-import { render, screen } from "@testing-library/react";
+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";
@@ -16,14 +16,14 @@ const config: DashboardLayoutConfig = {
   defaultTitle: "Workspace",
 };
 
-function renderAt(path: string, mainId?: string) {
+function renderAt(path: string, mainId?: string, configOverride?: DashboardLayoutConfig) {
   return render(
     <MemoryRouter initialEntries={[path]}>
       <Routes>
         <Route
           path="*"
           element={
-            <DashboardLayout config={config} mainId={mainId}>
+            <DashboardLayout config={configOverride ?? config} mainId={mainId}>
               {/* children are ignored — the layout renders an Outlet */}
             </DashboardLayout>
           }
@@ -55,3 +55,71 @@ describe("DashboardLayout (shell a11y)", () => {
     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();
+  });
+
+  it("derives navigation groups from the sidebar when includeSidebar is set", async () => {
+    renderAt("/", undefined, {
+      ...config,
+      commandPalette: {
+        includeSidebar: true,
+        groups: [{ heading: "Quick", items: [{ id: "q", label: "Quick action", onSelect: () => {} }] }],
+      },
+    });
+    fireEvent.keyDown(window, { key: "k", metaKey: true });
+    expect(await screen.findByRole("option", { name: "Quick action" })).toBeTruthy();
+    // The custom group has no "Home" — the one present is derived from the sidebar,
+    // carrying the path as its hint (accessible name "Home /").
+    const derived = screen.getByRole("option", { name: /home/i });
+    expect(derived.textContent).toContain("/");
+  });
+
+  it("omits sidebar-derived items from the palette by default", async () => {
+    renderAt("/", undefined, paletteConfig());
+    fireEvent.keyDown(window, { key: "k", metaKey: true });
+    // Only the palette's own "Home" (no path hint) — nothing derived from the sidebar.
+    const own = await screen.findByRole("option", { name: "Home" });
+    expect(own.textContent).toBe("Home");
+  });
+});

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

@@ -1,7 +1,8 @@
 import { useState, useEffect, type ReactNode } from "react";
-import { useLocation, Outlet, Navigate } from "react-router-dom";
+import { useLocation, useNavigate, 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";
@@ -60,10 +61,13 @@ export const DashboardLayout = ({
   skipToContentLabel,
 }: DashboardLayoutProps) => {
   const location = useLocation();
+  const navigate = useNavigate();
   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;
@@ -88,6 +92,18 @@ 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) => {
@@ -117,6 +133,23 @@ export const DashboardLayout = ({
 
   const currentTitle = getTitle();
 
+  // Sidebar-derived navigation groups — one nav definition feeds both chrome surfaces.
+  const paletteGroups = palette?.includeSidebar
+    ? [
+        ...palette.groups,
+        ...config.sidebarGroups.map((group) => ({
+          heading: group.title,
+          items: group.items.map((item) => ({
+            id: `nav-${item.path}`,
+            label: item.raw ? item.label : t(item.label),
+            icon: <item.icon size={16} aria-hidden="true" />,
+            hint: item.path,
+            onSelect: () => navigate(item.path),
+          })),
+        })),
+      ]
+    : undefined;
+
   const sidebarProps = {
     sidebarGroups: config.sidebarGroups,
     brandName: config.brandName,
@@ -175,7 +208,12 @@ 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}
@@ -200,6 +238,17 @@ export const DashboardLayout = ({
 
         {footer && <footer className="udb-layout__footer">{footer}</footer>}
       </div>
+
+      {palette && (
+        <CommandPalette
+          open={paletteOpen}
+          onOpenChange={setPaletteOpen}
+          groups={paletteGroups ?? palette.groups}
+          placeholder={palette.placeholder}
+          emptyLabel={palette.emptyLabel}
+          label={palette.label}
+        />
+      )}
     </div>
   );
 };

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

@@ -32,6 +32,21 @@ 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;
+    /** Append the sidebar groups as navigation groups — derived from
+     *  sidebarGroups and routed internally, so apps never map their nav twice. */
+    includeSidebar?: boolean;
+}
+
 export interface DashboardSidebarProps {
     collapsed: boolean;
     setCollapsed: (collapsed: boolean) => void;
@@ -51,6 +66,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). */