@umituz/web-dashboard 6.8.0 → 6.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/web-dashboard",
-  "version": "6.8.0",
+  "version": "6.10.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",
@@ -39,6 +39,10 @@
     "./settings/hooks": "./src/domains/settings/hooks/index.ts",
     "./settings/types": "./src/domains/settings/types/index.ts",
     "./settings/utils": "./src/domains/settings/utils/index.ts",
+    "./timing": "./src/domains/timing/index.ts",
+    "./timing/hooks": "./src/domains/timing/hooks/index.ts",
+    "./search": "./src/domains/search/index.ts",
+    "./search/utils": "./src/domains/search/searchItems.ts",
     "./styles.css": "./src/styles/dashboard.css"
   },
   "files": [

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

@@ -98,4 +98,28 @@ describe("DashboardLayout (command palette)", () => {
     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,5 +1,5 @@
 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";
@@ -61,6 +61,7 @@ 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);
@@ -132,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,
@@ -225,7 +243,7 @@ export const DashboardLayout = ({
         <CommandPalette
           open={paletteOpen}
           onOpenChange={setPaletteOpen}
-          groups={palette.groups}
+          groups={paletteGroups ?? palette.groups}
           placeholder={palette.placeholder}
           emptyLabel={palette.emptyLabel}
           label={palette.label}

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

@@ -42,6 +42,9 @@ export interface CommandPaletteConfig {
     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 {

package/src/domains/search/index.ts

@@ -0,0 +1,2 @@
+export { searchItems } from './searchItems';
+export type { SearchHit } from './searchItems';

package/src/domains/search/searchItems.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+import { searchItems } from './searchItems';
+
+interface Course {
+  id: string;
+  name: string;
+  blurb: string;
+  level: string;
+}
+
+const COURSES: Course[] = [
+  { id: 'c1', name: 'Present perfect workshop', blurb: 'Have you ever…', level: 'B1' },
+  { id: 'c2', name: 'IELTS reading sprint', blurb: 'Skimming strategies', level: 'C1' },
+  { id: 'c3', name: 'Everyday vocabulary', blurb: 'Present simple review', level: 'A1' },
+];
+
+const toHit = (c: Course) => ({ id: c.id, title: c.name, subtitle: c.blurb, category: c.level, to: `/courses/${c.id}` });
+
+describe('searchItems', () => {
+  it('returns nothing for empty or blank queries', () => {
+    expect(searchItems(COURSES, '', toHit)).toEqual([]);
+    expect(searchItems(COURSES, '   ', toHit)).toEqual([]);
+  });
+
+  it('matches titles case-insensitively and returns route hits', () => {
+    const hits = searchItems(COURSES, 'ielts', toHit);
+    expect(hits).toHaveLength(1);
+    expect(hits[0]).toMatchObject({ id: 'c2', title: 'IELTS reading sprint', to: '/courses/c2' });
+  });
+
+  it('ranks title matches above body-only matches', () => {
+    // "present" is in c1's title and c3's blurb — title wins.
+    const hits = searchItems(COURSES, 'present', toHit);
+    expect(hits[0]?.id).toBe('c1');
+    expect(hits).toHaveLength(2);
+  });
+
+  it('scores multi-term queries across fields', () => {
+    const hits = searchItems(COURSES, 'reading strategies', toHit);
+    expect(hits[0]?.id).toBe('c2');
+  });
+});

package/src/domains/search/searchItems.ts

@@ -0,0 +1,36 @@
+export interface SearchHit {
+  id: string;
+  title: string;
+  subtitle: string;
+  category: string;
+  to: string;
+}
+
+/** Case-insensitive substring scoring across a haystack of fields.
+ *  Title matches weigh 3×; every additional field hit adds 1. Empty
+ *  queries return no hits. Results are sorted by descending score. */
+export function searchItems<T extends object>(
+  items: readonly T[],
+  query: string,
+  toHit: (item: T) => Omit<SearchHit, 'id'> & { id?: string } & Record<string, unknown>,
+): SearchHit[] {
+  const q = query.trim().toLowerCase();
+  if (!q) return [];
+  const terms = q.split(/\s+/);
+  const hits: { hit: SearchHit; score: number }[] = [];
+  for (const item of items) {
+    const built = toHit(item);
+    const haystack =
+      `${built.title} ${built.subtitle} ${built.category} ${Object.values(item).filter((v) => typeof v === 'string').join(' ')}`.toLowerCase();
+    let score = 0;
+    for (const term of terms) {
+      if (built.title.toLowerCase().includes(term)) score += 3;
+      if (haystack.includes(term)) score += 1;
+    }
+    if (score > 0) {
+      const { title, subtitle, category, to, ...rest } = built;
+      hits.push({ hit: { id: (rest.id as string) ?? title, title, subtitle, category, to }, score });
+    }
+  }
+  return hits.sort((a, b) => b.score - a.score).map((h) => h.hit);
+}

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

@@ -0,0 +1 @@
+export { useCountdown, useStopwatch } from './useCountdown';

package/src/domains/timing/hooks/useCountdown.test.ts

@@ -0,0 +1,107 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
+import { useCountdown, useStopwatch } from './useCountdown';
+
+describe('useCountdown', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('ticks down once per second while running', () => {
+    const { result } = renderHook(() => useCountdown(3));
+    expect(result.current.remaining).toBe(3);
+    act(() => {
+      vi.advanceTimersByTime(2000);
+    });
+    expect(result.current.remaining).toBe(1);
+    expect(result.current.running).toBe(true);
+  });
+
+  it('fires onFinish exactly once at zero and stops', () => {
+    const onFinish = vi.fn();
+    const { result } = renderHook(() => useCountdown(2, onFinish));
+    act(() => {
+      vi.advanceTimersByTime(2000);
+    });
+    expect(result.current.remaining).toBe(0);
+    expect(result.current.running).toBe(false);
+    expect(onFinish).toHaveBeenCalledTimes(1);
+    act(() => {
+      vi.advanceTimersByTime(5000);
+    });
+    expect(onFinish).toHaveBeenCalledTimes(1);
+  });
+
+  it('restart rewinds the clock and re-arms completion', () => {
+    const onFinish = vi.fn();
+    const { result } = renderHook(() => useCountdown(1, onFinish));
+    act(() => {
+      vi.advanceTimersByTime(1000);
+    });
+    expect(onFinish).toHaveBeenCalledTimes(1);
+    act(() => {
+      result.current.restart();
+    });
+    expect(result.current.remaining).toBe(1);
+    expect(result.current.running).toBe(true);
+    act(() => {
+      vi.advanceTimersByTime(1000);
+    });
+    expect(onFinish).toHaveBeenCalledTimes(2);
+  });
+
+  it('pause halts the tick and start resumes it', () => {
+    const { result } = renderHook(() => useCountdown(5));
+    // state change and time travel must be separate acts — the interval
+    // effect only re-registers after the pause() commit
+    act(() => {
+      result.current.pause();
+    });
+    act(() => {
+      vi.advanceTimersByTime(3000);
+    });
+    expect(result.current.remaining).toBe(5);
+    act(() => {
+      result.current.start();
+    });
+    act(() => {
+      vi.advanceTimersByTime(1000);
+    });
+    expect(result.current.remaining).toBe(4);
+  });
+});
+
+describe('useStopwatch', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('counts up after start and freezes on stop', () => {
+    const { result } = renderHook(() => useStopwatch());
+    expect(result.current.elapsed).toBe(0);
+    act(() => {
+      result.current.start();
+    });
+    act(() => {
+      vi.advanceTimersByTime(3000);
+    });
+    expect(result.current.elapsed).toBe(3);
+    act(() => {
+      result.current.stop();
+    });
+    act(() => {
+      vi.advanceTimersByTime(3000);
+    });
+    expect(result.current.elapsed).toBe(3);
+    act(() => {
+      result.current.reset();
+    });
+    expect(result.current.elapsed).toBe(0);
+  });
+});

package/src/domains/timing/hooks/useCountdown.ts

@@ -0,0 +1,75 @@
+import { useEffect, useRef, useState } from 'react';
+
+/** Ticking countdown in seconds; fires onFinish once at zero. */
+export function useCountdown(seconds: number | null, onFinish?: () => void) {
+  const [remaining, setRemaining] = useState(seconds ?? 0);
+  const [running, setRunning] = useState(seconds != null);
+  const finishedRef = useRef(false);
+  const onFinishRef = useRef(onFinish);
+  onFinishRef.current = onFinish;
+
+  useEffect(() => {
+    setRemaining(seconds ?? 0);
+    setRunning(seconds != null);
+    finishedRef.current = false;
+  }, [seconds]);
+
+  const restart = () => {
+    finishedRef.current = false;
+    setRemaining(seconds ?? 0);
+    setRunning(seconds != null);
+  };
+
+  useEffect(() => {
+    if (!running) return;
+    const id = window.setInterval(() => {
+      setRemaining((r) => (r <= 1 ? 0 : r - 1));
+    }, 1000);
+    return () => window.clearInterval(id);
+  }, [running]);
+
+  // Completion fires in an effect, not inside the setRemaining updater —
+  // updaters must stay pure (StrictMode double-invokes them).
+  useEffect(() => {
+    if (running && remaining === 0 && !finishedRef.current) {
+      finishedRef.current = true;
+      setRunning(false);
+      onFinishRef.current?.();
+    }
+  }, [running, remaining]);
+
+  return {
+    remaining,
+    running,
+    start: () => setRunning(true),
+    pause: () => setRunning(false),
+    stop: () => {
+      setRunning(false);
+      finishedRef.current = true;
+    },
+    restart,
+  };
+}
+
+/** Stopwatch for open practice (writing time, speaking response windows). */
+export function useStopwatch() {
+  const [elapsed, setElapsed] = useState(0);
+  const [running, setRunning] = useState(false);
+
+  useEffect(() => {
+    if (!running) return;
+    const id = window.setInterval(() => setElapsed((e) => e + 1), 1000);
+    return () => window.clearInterval(id);
+  }, [running]);
+
+  return {
+    elapsed,
+    running,
+    start: () => setRunning(true),
+    stop: () => setRunning(false),
+    reset: () => {
+      setRunning(false);
+      setElapsed(0);
+    },
+  };
+}

package/src/domains/timing/index.ts

@@ -0,0 +1 @@
+export * from './hooks';