@umituz/web-dashboard 6.9.0 → 6.10.0

package/package.json

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