@slidev-react/client 0.2.5

package/src/features/presentation/location.ts

@@ -0,0 +1,113 @@
+import {
+  buildRolePathFromBase,
+  buildStandalonePathFromBase,
+  parsePresentationPath,
+  parseStandalonePath,
+  resolvePresentationBasePath,
+  type PresentationPathRole,
+} from "./path";
+
+export interface PresentationRouteMode {
+  kind: "role" | "standalone";
+  basePath: string;
+  role?: PresentationPathRole;
+}
+
+export interface SlidesLocationState {
+  index: number;
+  mode: PresentationRouteMode;
+}
+
+export interface SessionLocationState {
+  enabled: boolean;
+  role: "presenter" | "viewer";
+  currentSlideNumber: number;
+  normalizedPath: string | null;
+}
+
+export function clampSlideIndex(index: number, total: number): number {
+  return Math.min(Math.max(index, 0), Math.max(total - 1, 0));
+}
+
+export function resolveSlidesLocationState(pathname: string, total: number): SlidesLocationState {
+  const parsedPresentation = parsePresentationPath(pathname);
+  if (parsedPresentation) {
+    return {
+      index: clampSlideIndex((parsedPresentation.slideNumber ?? 1) - 1, total),
+      mode: {
+        kind: "role",
+        role: parsedPresentation.role,
+        basePath: parsedPresentation.basePath,
+      },
+    };
+  }
+
+  const parsedStandalone = parseStandalonePath(pathname);
+  if (parsedStandalone) {
+    return {
+      index: clampSlideIndex(parsedStandalone.slideNumber - 1, total),
+      mode: {
+        kind: "standalone",
+        basePath: parsedStandalone.basePath,
+      },
+    };
+  }
+
+  return {
+    index: clampSlideIndex(0, total),
+    mode: {
+      kind: "standalone",
+      basePath: resolvePresentationBasePath(pathname),
+    },
+  };
+}
+
+export function resolveSessionLocationState(pathname: string): SessionLocationState {
+  const parsedPresentation = parsePresentationPath(pathname);
+  if (parsedPresentation) {
+    const currentSlideNumber = parsedPresentation.slideNumber ?? 1;
+    return {
+      enabled: true,
+      role: "presenter",
+      currentSlideNumber,
+      normalizedPath: buildRolePathFromBase(
+        parsedPresentation.basePath,
+        parsedPresentation.role,
+        currentSlideNumber,
+      ),
+    };
+  }
+
+  const parsedStandalone = parseStandalonePath(pathname);
+  if (parsedStandalone) {
+    return {
+      enabled: true,
+      role: "viewer",
+      currentSlideNumber: parsedStandalone.slideNumber,
+      normalizedPath: buildStandalonePathFromBase(
+        parsedStandalone.basePath,
+        parsedStandalone.slideNumber,
+      ),
+    };
+  }
+
+  return {
+    enabled: false,
+    role: "viewer",
+    currentSlideNumber: 1,
+    normalizedPath: null,
+  };
+}
+
+export function buildSlidesPath(mode: PresentationRouteMode, index: number) {
+  const slideNumber = index + 1;
+  return mode.kind === "role"
+    ? buildRolePathFromBase(mode.basePath, mode.role ?? "presenter", slideNumber)
+    : buildStandalonePathFromBase(mode.basePath, slideNumber);
+}
+
+export function normalizePathname(pathname: string) {
+  if (pathname.length > 1 && pathname.endsWith("/")) return pathname.slice(0, -1);
+
+  return pathname;
+}

package/src/features/presentation/navigation/KeyboardController.tsx

@@ -0,0 +1,73 @@
+import { useEffect } from "react";
+import { useReveal } from "../reveal/RevealContext";
+import { resolveNavigationShortcutAction } from "./keyboardShortcuts";
+import { useSlidesNavigation } from "./useSlidesNavigation";
+import { isTypingElement } from "../browser";
+
+export function KeyboardController({
+  enabled = true,
+  overlayOpen = false,
+  onAdvance,
+  onRetreat,
+  onFirst,
+  onLast,
+}: {
+  enabled?: boolean;
+  overlayOpen?: boolean;
+  onAdvance?: () => void;
+  onRetreat?: () => void;
+  onFirst?: () => void;
+  onLast?: () => void;
+}) {
+  const navigation = useSlidesNavigation();
+  const reveal = useReveal();
+
+  useEffect(() => {
+    if (!enabled) return;
+
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (isTypingElement(event.target)) return;
+
+      if (overlayOpen) return;
+
+      const action = resolveNavigationShortcutAction({
+        key: event.key,
+        shiftKey: event.shiftKey,
+      });
+      if (!action) return;
+
+      event.preventDefault();
+
+      if (action === "advance") {
+        if (onAdvance) onAdvance();
+        else if (reveal) reveal.advance();
+        else navigation.next();
+        return;
+      }
+
+      if (action === "retreat") {
+        if (onRetreat) onRetreat();
+        else if (reveal) reveal.retreat();
+        else navigation.prev();
+        return;
+      }
+
+      if (action === "first") {
+        if (onFirst) onFirst();
+        else navigation.first();
+        return;
+      }
+
+      if (action === "last") {
+        event.preventDefault();
+        if (onLast) onLast();
+        else navigation.last();
+      }
+    };
+
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [enabled, navigation, onAdvance, onFirst, onLast, onRetreat, overlayOpen, reveal]);
+
+  return null;
+}

package/src/features/presentation/navigation/PresentationNavbar.tsx

@@ -0,0 +1,162 @@
+import {
+  BookOpenText,
+  ChevronLeft,
+  ChevronRight,
+  Keyboard,
+  LayoutGrid,
+  NotebookText,
+  PenLine,
+  Radio,
+} from "lucide-react";
+import { useState } from "react";
+import { useDraw } from "../draw/DrawProvider";
+import { ChromeIconButton } from "../../../ui/primitives/ChromeIconButton";
+
+function DrawControls() {
+  const draw = useDraw();
+
+  return (
+    <ChromeIconButton
+      onClick={draw.toggleEnabled}
+      title="Toggle draw (D)"
+      aria-label="Toggle draw mode"
+      tone={draw.enabled ? "active" : "default"}
+      size="sm"
+      radius="soft"
+    >
+      <PenLine size={16} />
+    </ChromeIconButton>
+  );
+}
+
+export function PresentationNavbar({
+  slideTitle,
+  currentIndex,
+  total,
+  canPrev,
+  canNext,
+  showPresenterModeButton,
+  overviewOpen,
+  notesOpen,
+  shortcutsOpen,
+  canOpenOverview,
+  onEnterPresenterMode,
+  onToggleOverview,
+  onToggleNotes,
+  onToggleShortcuts,
+  onPrev,
+  onNext,
+  canControl,
+}: {
+  slideTitle?: string;
+  currentIndex: number;
+  total: number;
+  canPrev: boolean;
+  canNext: boolean;
+  showPresenterModeButton: boolean;
+  overviewOpen: boolean;
+  notesOpen: boolean;
+  shortcutsOpen: boolean;
+  canOpenOverview: boolean;
+  onEnterPresenterMode?: () => void;
+  onToggleOverview: () => void;
+  onToggleNotes: () => void;
+  onToggleShortcuts: () => void;
+  onPrev: () => void;
+  onNext: () => void;
+  canControl: boolean;
+}) {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <div
+      className="absolute bottom-0 left-4 z-40"
+      onMouseEnter={() => setOpen(true)}
+      onMouseLeave={() => setOpen(false)}
+    >
+      <div aria-hidden className="h-14 w-20 rounded-t-2xl" />
+      <nav
+        className={`absolute bottom-0 left-0 flex items-center gap-1 rounded-t-xl border border-b-0 border-slate-200 bg-white/95 px-2 py-1.5 text-slate-800  ring-1 ring-black/5 backdrop-blur-md transition-[opacity,transform] ${open ? "pointer-events-auto translate-y-0 opacity-100 duration-0" : "pointer-events-none translate-y-2 opacity-0 duration-180"}`}
+        aria-label="Presentation navbar"
+      >
+        <ChromeIconButton
+          title={`${slideTitle ?? "Slide"} (${currentIndex + 1}/${total})`}
+          aria-label="Current slide info"
+          size="sm"
+          radius="soft"
+        >
+          <BookOpenText size={15} />
+        </ChromeIconButton>
+        <ChromeIconButton
+          onClick={onToggleShortcuts}
+          title="Keyboard shortcuts (?)"
+          aria-label="Toggle keyboard shortcuts"
+          tone={shortcutsOpen ? "active" : "default"}
+          size="sm"
+          radius="soft"
+        >
+          <Keyboard size={15} />
+        </ChromeIconButton>
+        <ChromeIconButton
+          onClick={onToggleNotes}
+          title="Notes Workspace (N)"
+          aria-label="Toggle notes workspace"
+          tone={notesOpen ? "active" : "default"}
+          size="sm"
+          radius="soft"
+          disabled={!canControl}
+        >
+          <NotebookText size={16} />
+        </ChromeIconButton>
+        <ChromeIconButton
+          onClick={onToggleOverview}
+          title="Quick Overview (O)"
+          aria-label="Toggle quick overview"
+          tone={overviewOpen ? "active" : "default"}
+          size="sm"
+          radius="soft"
+          disabled={!canOpenOverview}
+        >
+          <LayoutGrid size={16} />
+        </ChromeIconButton>
+        {showPresenterModeButton && (
+          <ChromeIconButton
+            onClick={onEnterPresenterMode}
+            title="Enter presenter mode"
+            aria-label="Enter presenter mode"
+            size="sm"
+            radius="soft"
+          >
+            <Radio size={15} />
+          </ChromeIconButton>
+        )}
+        {canControl && (
+          <>
+            <ChromeIconButton
+              onClick={onPrev}
+              disabled={!canPrev}
+              title="Previous slide"
+              aria-label="Previous slide"
+              size="sm"
+              radius="soft"
+            >
+              <ChevronLeft size={16} />
+            </ChromeIconButton>
+            <ChromeIconButton
+              onClick={onNext}
+              disabled={!canNext}
+              title="Next slide"
+              aria-label="Next slide"
+              size="sm"
+              radius="soft"
+            >
+              <ChevronRight size={16} />
+            </ChromeIconButton>
+            <div className="mx-1 h-5 w-px bg-slate-200" aria-hidden />
+            <DrawControls />
+          </>
+        )}
+      </nav>
+    </div>
+  );
+}

package/src/features/presentation/navigation/ShortcutsHelpOverlay.test.tsx

@@ -0,0 +1,24 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { ShortcutsHelpOverlay } from "./ShortcutsHelpOverlay";
+import { buildShortcutHelpSections } from "./keyboardShortcuts";
+
+describe("ShortcutsHelpOverlay", () => {
+  it("renders the supported shortcut groups and help triggers", () => {
+    const html = renderToStaticMarkup(
+      <ShortcutsHelpOverlay
+        open
+        sections={buildShortcutHelpSections({
+          canControl: true,
+          canOpenOverview: true,
+        })}
+        onClose={() => {}}
+      />,
+    );
+
+    expect(html).toContain("Keyboard Shortcuts");
+    expect(html).toContain("Shift Shift");
+    expect(html).toContain("Toggle quick overview");
+    expect(html).toContain("Toggle draw mode");
+  });
+});

package/src/features/presentation/navigation/ShortcutsHelpOverlay.tsx

@@ -0,0 +1,111 @@
+import { Keyboard, X } from "lucide-react";
+import { ChromeIconButton } from "../../../ui/primitives/ChromeIconButton";
+import { ChromePanel } from "../../../ui/primitives/ChromePanel";
+import { ChromeTag } from "../../../ui/primitives/ChromeTag";
+import type { ShortcutHelpSection } from "./keyboardShortcuts";
+
+function ShortcutKeys({ value }: { value: string }) {
+  return (
+    <div className="flex flex-wrap items-center gap-1">
+      {value.split(" / ").map((part, index, list) => (
+        <span key={`${part}-${index}`} className="inline-flex items-center gap-1">
+          <kbd className="rounded-md border border-slate-200 bg-white px-1.5 py-0.5 font-mono text-[10px] font-semibold text-slate-700 shadow-[inset_0_1px_0_rgba(255,255,255,0.72)]">
+            {part}
+          </kbd>
+          {index < list.length - 1 ? <span className="text-[10px] text-slate-300">/</span> : null}
+        </span>
+      ))}
+    </div>
+  );
+}
+
+export function ShortcutsHelpOverlay({
+  open,
+  sections,
+  onClose,
+}: {
+  open: boolean;
+  sections: ShortcutHelpSection[];
+  onClose: () => void;
+}) {
+  if (!open) return null;
+
+  return (
+    <div className="absolute inset-0 z-50 bg-black/30 backdrop-blur-sm">
+      <div className="mx-auto flex h-full w-full max-w-[1640px] items-center justify-center px-4 py-4 sm:px-6">
+        <ChromePanel
+          tone="solid"
+          radius="section"
+          padding="none"
+          className="flex max-h-full w-full max-w-[1180px] flex-col overflow-hidden bg-white/90"
+        >
+          <header className="border-b border-slate-200/80 px-4 py-4 sm:px-5">
+            <div className="flex items-start justify-between gap-4">
+              <div className="min-w-0">
+                <div className="mb-2 flex flex-wrap items-center gap-2">
+                  <ChromeTag
+                    tone="active"
+                    size="sm"
+                    weight="semibold"
+                    className="uppercase tracking-[0.18em]"
+                  >
+                    <Keyboard size={13} />
+                    Keyboard Shortcuts
+                  </ChromeTag>
+                  <ChromeTag size="sm">Press `?` or double-tap `Shift`</ChromeTag>
+                </div>
+                <h2 className="text-lg font-semibold text-slate-950 sm:text-xl">
+                  Everything the runtime can do from the keyboard
+                </h2>
+                <p className="mt-1.5 max-w-3xl text-sm leading-5 text-slate-600">
+                  This list only shows shortcuts that are actually implemented right now, so it
+                  stays trustworthy as the product evolves.
+                </p>
+              </div>
+              <ChromeIconButton
+                onClick={onClose}
+                aria-label="Close keyboard shortcuts"
+                title="Close keyboard shortcuts"
+                className="rounded-full"
+              >
+                <X size={18} />
+              </ChromeIconButton>
+            </div>
+          </header>
+          <div className="min-h-0 overflow-auto px-4 py-4 sm:px-5 sm:py-5">
+            <div className="grid gap-3 lg:grid-cols-3">
+              {sections.map((section) => (
+                <ChromePanel
+                  key={section.title}
+                  tone="frame"
+                  radius="section"
+                  className="overflow-hidden border border-slate-200/80 bg-slate-50/72"
+                >
+                  <div className="border-b border-slate-200/75 px-3.5 py-3">
+                    <h3 className="text-[11px] font-semibold uppercase tracking-[0.18em] text-slate-700">
+                      {section.title}
+                    </h3>
+                    <p className="mt-1.5 text-xs leading-5 text-slate-500">{section.description}</p>
+                  </div>
+                  <div className="px-3 py-2.5">
+                    <div className="space-y-2">
+                      {section.items.map((item) => (
+                        <div
+                          key={`${section.title}:${item.keys}:${item.action}`}
+                          className="flex flex-col gap-1.5 rounded-md border border-white/80 bg-white/82 px-2.5 py-2.5"
+                        >
+                          <ShortcutKeys value={item.keys} />
+                          <div className="text-[13px] leading-5 text-slate-700">{item.action}</div>
+                        </div>
+                      ))}
+                    </div>
+                  </div>
+                </ChromePanel>
+              ))}
+            </div>
+          </div>
+        </ChromePanel>
+      </div>
+    </div>
+  );
+}

package/src/features/presentation/navigation/keyboardShortcuts.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildShortcutHelpSections,
+  createShortcutHelpTriggerState,
+  isShortcutHelpOpenKey,
+  registerShortcutHelpKeyDown,
+  registerShortcutHelpKeyUp,
+  resolveNavigationShortcutAction,
+} from "./keyboardShortcuts";
+
+describe("keyboardShortcuts", () => {
+  it("treats shift+space as retreat and plain space as advance", () => {
+    expect(resolveNavigationShortcutAction({ key: " ", shiftKey: false })).toBe("advance");
+    expect(resolveNavigationShortcutAction({ key: " ", shiftKey: true })).toBe("retreat");
+  });
+
+  it("detects question-mark help shortcut without modifiers", () => {
+    expect(
+      isShortcutHelpOpenKey({
+        key: "?",
+        shiftKey: true,
+        metaKey: false,
+        ctrlKey: false,
+        altKey: false,
+      }),
+    ).toBe(true);
+
+    expect(
+      isShortcutHelpOpenKey({
+        key: "?",
+        shiftKey: true,
+        metaKey: true,
+        ctrlKey: false,
+        altKey: false,
+      }),
+    ).toBe(false);
+  });
+
+  it("toggles on an isolated double shift tap", () => {
+    let state = createShortcutHelpTriggerState();
+
+    state = registerShortcutHelpKeyDown(state, "Shift");
+    let result = registerShortcutHelpKeyUp(state, "Shift", 100);
+    expect(result.shouldToggle).toBe(false);
+
+    state = registerShortcutHelpKeyDown(result.nextState, "Shift");
+    result = registerShortcutHelpKeyUp(state, "Shift", 320);
+    expect(result.shouldToggle).toBe(true);
+  });
+
+  it("does not toggle when shift was used as part of another shortcut chord", () => {
+    let state = createShortcutHelpTriggerState();
+
+    state = registerShortcutHelpKeyDown(state, "Shift");
+    state = registerShortcutHelpKeyDown(state, "/");
+
+    const result = registerShortcutHelpKeyUp(state, "Shift", 220);
+    expect(result.shouldToggle).toBe(false);
+  });
+
+  it("only includes draw shortcuts when local control is available", () => {
+    const viewerSections = buildShortcutHelpSections({
+      canControl: false,
+      canOpenOverview: true,
+    });
+    const presenterSections = buildShortcutHelpSections({
+      canControl: true,
+      canOpenOverview: true,
+    });
+
+    expect(viewerSections.some((section) => section.title === "Draw")).toBe(false);
+    expect(presenterSections.some((section) => section.title === "Draw")).toBe(true);
+  });
+});