@slidev-react/client 0.2.5

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

@@ -0,0 +1,221 @@
+export const SHORTCUT_HELP_DOUBLE_SHIFT_MS = 400;
+
+export type NavigationShortcutAction = "advance" | "retreat" | "first" | "last";
+
+export type ShortcutHelpItem = {
+  keys: string;
+  action: string;
+};
+
+export type ShortcutHelpSection = {
+  title: string;
+  description: string;
+  items: ShortcutHelpItem[];
+};
+
+export type ShortcutHelpTriggerState = {
+  shiftPressed: boolean;
+  shiftChordActive: boolean;
+  lastIsolatedShiftAt: number | null;
+};
+
+export function resolveNavigationShortcutAction({
+  key,
+  shiftKey,
+}: {
+  key: string;
+  shiftKey: boolean;
+}): NavigationShortcutAction | null {
+  if (key === "ArrowRight" || key === "PageDown") return "advance";
+  if (key === "ArrowLeft" || key === "PageUp") return "retreat";
+  if (key === "Home") return "first";
+  if (key === "End") return "last";
+  if (key === " ") return shiftKey ? "retreat" : "advance";
+
+  return null;
+}
+
+export function createShortcutHelpTriggerState(): ShortcutHelpTriggerState {
+  return {
+    shiftPressed: false,
+    shiftChordActive: false,
+    lastIsolatedShiftAt: null,
+  };
+}
+
+export function registerShortcutHelpKeyDown(
+  state: ShortcutHelpTriggerState,
+  key: string,
+): ShortcutHelpTriggerState {
+  if (key === "Shift") {
+    return {
+      ...state,
+      shiftPressed: true,
+      shiftChordActive: false,
+    };
+  }
+
+  if (!state.shiftPressed) return state;
+
+  return {
+    ...state,
+    shiftChordActive: true,
+  };
+}
+
+export function registerShortcutHelpKeyUp(
+  state: ShortcutHelpTriggerState,
+  key: string,
+  releasedAt: number,
+  thresholdMs = SHORTCUT_HELP_DOUBLE_SHIFT_MS,
+) {
+  if (key !== "Shift") {
+    return {
+      nextState: state,
+      shouldToggle: false,
+    };
+  }
+
+  const isolatedTap = state.shiftPressed && !state.shiftChordActive;
+  const shouldToggle =
+    isolatedTap &&
+    state.lastIsolatedShiftAt != null &&
+    releasedAt - state.lastIsolatedShiftAt <= thresholdMs;
+
+  return {
+    nextState: {
+      shiftPressed: false,
+      shiftChordActive: false,
+      lastIsolatedShiftAt: isolatedTap
+        ? shouldToggle
+          ? null
+          : releasedAt
+        : state.lastIsolatedShiftAt,
+    },
+    shouldToggle,
+  };
+}
+
+export function isShortcutHelpOpenKey({
+  key,
+  shiftKey,
+  metaKey,
+  ctrlKey,
+  altKey,
+}: {
+  key: string;
+  shiftKey: boolean;
+  metaKey: boolean;
+  ctrlKey: boolean;
+  altKey: boolean;
+}) {
+  if (metaKey || ctrlKey || altKey) return false;
+
+  return key === "?" || (key === "/" && shiftKey);
+}
+
+export function buildShortcutHelpSections({
+  canControl,
+  canOpenOverview,
+}: {
+  canControl: boolean;
+  canOpenOverview: boolean;
+}): ShortcutHelpSection[] {
+  const sections: ShortcutHelpSection[] = [
+    {
+      title: "Navigation",
+      description: "Move through the slides without leaving the keyboard.",
+      items: [
+        {
+          keys: "Right / Space / PageDown",
+          action: "Next cue or next slide",
+        },
+        {
+          keys: "Left / Shift + Space / PageUp",
+          action: "Previous cue or previous slide",
+        },
+        {
+          keys: "Home",
+          action: "Jump to the first slide",
+        },
+        {
+          keys: "End",
+          action: "Jump to the last slide",
+        },
+      ],
+    },
+    {
+      title: "Overlays",
+      description: "Open, switch, and close the main workspaces.",
+      items: [
+        {
+          keys: "?",
+          action: "Toggle keyboard shortcuts help",
+        },
+        {
+          keys: "Shift Shift",
+          action: "Toggle keyboard shortcuts help",
+        },
+        {
+          keys: "Esc",
+          action: "Close the current overlay",
+        },
+        ...(canOpenOverview
+          ? [
+              {
+                keys: "O",
+                action: "Toggle quick overview",
+              },
+            ]
+          : []),
+        ...(canControl
+          ? [
+              {
+                keys: "N",
+                action: "Toggle notes workspace",
+              },
+            ]
+          : []),
+      ],
+    },
+  ];
+
+  if (canControl) {
+    sections.push({
+      title: "Draw",
+      description: "Control live annotation tools while presenting.",
+      items: [
+        {
+          keys: "D",
+          action: "Toggle draw mode",
+        },
+        {
+          keys: "P",
+          action: "Switch to pen",
+        },
+        {
+          keys: "B",
+          action: "Switch to circle",
+        },
+        {
+          keys: "R",
+          action: "Switch to rectangle",
+        },
+        {
+          keys: "E",
+          action: "Switch to eraser",
+        },
+        {
+          keys: "C",
+          action: "Clear strokes on the current slide",
+        },
+        {
+          keys: "Cmd/Ctrl + Z",
+          action: "Undo the last stroke",
+        },
+      ],
+    });
+  }
+
+  return sections;
+}

package/src/features/presentation/navigation/useSlidesNavigation.ts

@@ -0,0 +1,15 @@
+import { useSlidesState } from "../../../app/providers/SlidesNavigationProvider";
+
+export function useSlidesNavigation() {
+  const slides = useSlidesState();
+
+  return {
+    currentIndex: slides.currentIndex,
+    total: slides.total,
+    next: slides.next,
+    prev: slides.prev,
+    first: slides.first,
+    last: slides.last,
+    goTo: slides.goTo,
+  };
+}

package/src/features/presentation/overview/NotesOverview.tsx

@@ -0,0 +1,200 @@
+import { NotebookText, X } from "lucide-react";
+import { useEffect, useMemo, useState } from "react";
+import type { CompiledSlide } from "../presenter/types";
+import { ChromePanel } from "../../../ui/primitives/ChromePanel";
+
+function summarizeNotes(notes?: string) {
+  if (!notes) return "No speaker notes yet.";
+
+  const normalized = notes.replace(/\s+/g, " ").trim();
+  if (normalized.length <= 140) return normalized;
+
+  return `${normalized.slice(0, 137)}...`;
+}
+
+function toParagraphs(notes?: string) {
+  if (!notes) return [];
+
+  return notes
+    .split(/\n\s*\n/g)
+    .map((section) => section.trim())
+    .filter(Boolean);
+}
+
+export function NotesOverview({
+  open,
+  slides,
+  currentIndex,
+  onClose,
+  onSelect,
+}: {
+  open: boolean;
+  slides: CompiledSlide[];
+  currentIndex: number;
+  onClose: () => void;
+  onSelect: (index: number) => void;
+}) {
+  const [selectedIndex, setSelectedIndex] = useState(currentIndex);
+
+  useEffect(() => {
+    if (!open) return;
+
+    setSelectedIndex(currentIndex);
+  }, [currentIndex, open]);
+
+  const selectedSlide = slides[selectedIndex] ?? slides[currentIndex] ?? null;
+  const notedSlidesCount = useMemo(
+    () => slides.filter((slide) => Boolean(slide.meta.notes?.trim())).length,
+    [slides],
+  );
+  const selectedNotes = toParagraphs(selectedSlide?.meta.notes);
+
+  if (!open) return null;
+
+  return (
+    <div className="absolute inset-0 z-50 bg-slate-100/84 backdrop-blur-sm">
+      <div className="mx-auto flex h-full w-full max-w-[1800px] flex-col px-6 py-6">
+        <header className="mb-4 flex items-start justify-between gap-6">
+          <div className="text-slate-900">
+            <div className="mb-2 inline-flex items-center gap-2 rounded-full border border-slate-200 bg-white/90 px-3 py-1 text-xs font-medium text-slate-600">
+              <NotebookText size={14} />
+              <span>
+                {notedSlidesCount}/{slides.length} slides have notes
+              </span>
+            </div>
+            <h2 className="text-lg font-semibold">Notes Workspace</h2>
+            <p className="text-sm text-slate-600">
+              Review the whole narrative, then jump directly to the slide you want to rehearse.
+              Press `N` or `Esc` to close.
+            </p>
+          </div>
+          <button
+            type="button"
+            onClick={onClose}
+            aria-label="Close notes workspace"
+            className="inline-flex size-10 items-center justify-center rounded-lg border border-slate-300 bg-white text-slate-700 hover:bg-slate-50"
+          >
+            <X size={18} />
+          </button>
+        </header>
+        <div className="grid min-h-0 flex-1 gap-4 xl:grid-cols-[minmax(340px,420px)_minmax(0,1fr)]">
+          <ChromePanel tone="solid" radius="section" padding="none" className="overflow-hidden">
+            <div className="border-b border-slate-200/80 px-5 py-4">
+              <h3 className="text-sm font-semibold text-slate-900">Slide Notes Index</h3>
+              <p className="mt-1 text-sm text-slate-500">
+                Every slide is listed here, including the ones that still need notes.
+              </p>
+            </div>
+            <div className="min-h-0 overflow-auto p-3">
+              <div className="space-y-2">
+                {slides.map((slide, index) => {
+                  const active = index === selectedIndex;
+                  const isCurrent = index === currentIndex;
+                  const hasNotes = Boolean(slide.meta.notes?.trim());
+
+                  return (
+                    <button
+                      key={slide.id}
+                      type="button"
+                      onClick={() => setSelectedIndex(index)}
+                      className={`w-full rounded-lg border p-4 text-left transition ${
+                        active
+                          ? "border-emerald-400 bg-emerald-50 "
+                          : "border-slate-200 bg-white hover:border-slate-300 hover:bg-slate-50"
+                      }`}
+                    >
+                      <div className="mb-2 flex items-center justify-between gap-3">
+                        <div className="flex items-center gap-2">
+                          <span className="rounded-md bg-slate-100 px-2 py-0.5 text-xs font-semibold text-slate-700">
+                            {index + 1}
+                          </span>
+                          {isCurrent && (
+                            <span className="rounded-md bg-emerald-100 px-2 py-0.5 text-xs font-medium text-emerald-700">
+                              Current
+                            </span>
+                          )}
+                        </div>
+                        <span
+                          className={`rounded-md px-2 py-0.5 text-xs font-medium ${
+                            hasNotes
+                              ? "bg-emerald-100 text-emerald-700"
+                              : "bg-slate-100 text-slate-500"
+                          }`}
+                        >
+                          {hasNotes ? "Notes ready" : "No notes"}
+                        </span>
+                      </div>
+                      <div className="text-sm font-semibold text-slate-900">
+                        {slide.meta.title ?? `Slide ${index + 1}`}
+                      </div>
+                      <p className="mt-2 text-sm leading-6 text-slate-500">
+                        {summarizeNotes(slide.meta.notes)}
+                      </p>
+                    </button>
+                  );
+                })}
+              </div>
+            </div>
+          </ChromePanel>
+          <ChromePanel
+            tone="solid"
+            radius="section"
+            padding="none"
+            className="flex flex-col overflow-hidden"
+          >
+            <div className="border-b border-slate-200/80 px-6 py-5">
+              <div className="mb-3 flex flex-wrap items-center gap-2">
+                <span className="rounded-md bg-slate-100 px-2 py-0.5 text-xs font-semibold text-slate-700">
+                  {selectedIndex + 1}
+                </span>
+                {selectedSlide?.meta.layout && (
+                  <span className="rounded-md bg-slate-100 px-2 py-0.5 text-xs text-slate-500">
+                    {selectedSlide.meta.layout}
+                  </span>
+                )}
+              </div>
+              <div className="flex flex-col gap-4 md:flex-row md:items-end md:justify-between">
+                <div>
+                  <h3 className="text-lg font-semibold text-slate-900">
+                    {selectedSlide?.meta.title ?? `Slide ${selectedIndex + 1}`}
+                  </h3>
+                  <p className="mt-1 text-sm text-slate-500">
+                    {selectedSlide?.meta.notes?.trim()
+                      ? "Full speaker notes for the selected slide."
+                      : "This slide still needs presenter notes."}
+                  </p>
+                </div>
+                <button
+                  type="button"
+                  onClick={() => onSelect(selectedIndex)}
+                  className="inline-flex items-center justify-center rounded-lg bg-slate-900 px-4 py-2 text-sm font-medium text-white hover:bg-slate-800"
+                >
+                  Jump To Slide
+                </button>
+              </div>
+            </div>
+            <div className="min-h-0 flex-1 overflow-auto px-6 py-5">
+              {selectedNotes.length > 0 ? (
+                <div className="space-y-4 text-[15px] leading-7 text-slate-600">
+                  {selectedNotes.map((paragraph, index) => (
+                    <p key={`${index}-${paragraph.slice(0, 24)}`} className="whitespace-pre-wrap">
+                      {paragraph}
+                    </p>
+                  ))}
+                </div>
+              ) : (
+                <div className="rounded-2xl border border-dashed border-slate-200 bg-slate-50/80 p-6">
+                  <p className="font-medium text-slate-900">No notes on this slide yet.</p>
+                  <p className="mt-2 text-sm leading-6 text-slate-500">
+                    Add slide frontmatter with <code>notes: |</code> to capture your framing,
+                    punchlines, and the line you do not want to improvise live.
+                  </p>
+                </div>
+              )}
+            </div>
+          </ChromePanel>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/features/presentation/overview/QuickOverview.tsx

@@ -0,0 +1,126 @@
+import type { KeyboardEvent } from "react";
+import { X } from "lucide-react";
+import { formatViewportAspectRatio } from "@slidev-react/core/slides/viewport";
+import type { CompiledSlide, SlidesConfig } from "../presenter/types";
+import { ChromeIconButton } from "../../../ui/primitives/ChromeIconButton";
+import { ChromePanel } from "../../../ui/primitives/ChromePanel";
+import { ChromeTag } from "../../../ui/primitives/ChromeTag";
+import { SlidePreviewSurface } from "../stage/SlidePreviewSurface";
+
+function OverviewSlidePreview({
+  index,
+  active,
+  slide,
+  slidesConfig,
+}: {
+  index: number;
+  active: boolean;
+  slide: CompiledSlide;
+  slidesConfig: Pick<SlidesConfig, "slidesViewport" | "slidesLayout" | "slidesBackground">;
+}) {
+  const { slidesViewport, slidesLayout, slidesBackground } = slidesConfig;
+  return (
+    <div
+      style={{ aspectRatio: formatViewportAspectRatio(slidesViewport) }}
+      className={`relative mb-0 w-full overflow-hidden rounded-t-md rounded-b-none bg-slate-100/72  ${active ? "ring-1 ring-emerald-200/80" : ""}`}
+    >
+      <span className="absolute top-2 left-2 z-10">
+        <ChromeTag tone={active ? "active" : "default"} size="xs" weight="semibold">
+          {index + 1}
+        </ChromeTag>
+      </span>
+      {slide.meta.layout && (
+        <span className="absolute top-2 right-2 z-10">
+          <ChromeTag size="xs">{slide.meta.layout}</ChromeTag>
+        </span>
+      )}
+      <SlidePreviewSurface
+        Slide={slide.component}
+        meta={slide.meta}
+        slidesConfig={slidesConfig}
+        viewportClassName="size-full"
+        stageClassName="pointer-events-none select-none"
+      />
+    </div>
+  );
+}
+
+export function QuickOverview({
+  open,
+  slides,
+  currentIndex,
+  slidesConfig,
+  onClose,
+  onSelect,
+}: {
+  open: boolean;
+  slides: CompiledSlide[];
+  currentIndex: number;
+  slidesConfig: Pick<SlidesConfig, "slidesViewport" | "slidesLayout" | "slidesBackground">;
+  onClose: () => void;
+  onSelect: (index: number) => void;
+}) {
+  function handleSelectKeyDown(event: KeyboardEvent<HTMLElement>, index: number) {
+    if (event.key !== "Enter" && event.key !== " ") return;
+    event.preventDefault();
+    onSelect(index);
+  }
+
+  if (!open) return null;
+
+  return (
+    <div className="absolute inset-0 z-50 bg-slate-100/84 backdrop-blur-md">
+      <div className="mx-auto flex h-full w-full max-w-[2200px] flex-col px-6 py-6">
+        <header className="mb-5 flex items-center justify-between">
+          <div className="text-slate-900">
+            <h2 className="text-lg font-semibold">Quick Overview</h2>
+            <p className="text-sm text-slate-600">
+              Click a slide to jump. Press `O` or `Esc` to close.
+            </p>
+          </div>
+          <ChromeIconButton
+            onClick={onClose}
+            aria-label="Close quick overview"
+            className="rounded-full "
+          >
+            <X size={18} />
+          </ChromeIconButton>
+        </header>
+        <div className="min-h-0 flex-1 overflow-auto pr-1">
+          <div className="grid grid-cols-[repeat(auto-fit,minmax(360px,1fr))] gap-5">
+            {slides.map((slide, index) => {
+              const active = index === currentIndex;
+              return (
+                <ChromePanel
+                  key={slide.id}
+                  as="article"
+                  role="button"
+                  tabIndex={0}
+                  onClick={() => onSelect(index)}
+                  onKeyDown={(event: KeyboardEvent<HTMLElement>) =>
+                    handleSelectKeyDown(event, index)
+                  }
+                  className={`group cursor-pointer overflow-hidden p-0 text-left transition focus:outline-none focus:ring-2 focus:ring-emerald-300/70 ${active ? "bg-white ring-1 ring-emerald-300/70" : "bg-white/90 ring-1 ring-transparent hover:bg-white/92  hover:ring-slate-300/70"}`}
+                  aria-label={`Go to slide ${index + 1}`}
+                  tone="solid"
+                  radius="section"
+                  padding="none"
+                >
+                  <OverviewSlidePreview
+                    index={index}
+                    active={active}
+                    slide={slide}
+                    slidesConfig={slidesConfig}
+                  />
+                  <div className="truncate px-2.5 py-2 text-sm font-medium text-slate-900">
+                    {slide.meta.title ?? `Slide ${index + 1}`}
+                  </div>
+                </ChromePanel>
+              );
+            })}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/features/presentation/path.ts

@@ -0,0 +1,137 @@
+export type PresentationPathRole = "presenter";
+
+const ROLE_SET: ReadonlySet<PresentationPathRole> = new Set(["presenter"]);
+
+export interface ParsedPresentationPath {
+  role: PresentationPathRole;
+  slideNumber: number | null;
+  basePath: string;
+}
+
+export interface ParsedStandalonePath {
+  slideNumber: number;
+  basePath: string;
+}
+
+function normalizePath(pathname: string) {
+  if (!pathname) return "/";
+
+  if (pathname.length > 1 && pathname.endsWith("/")) return pathname.slice(0, -1);
+
+  return pathname;
+}
+
+function normalizeBasePath(basePath: string) {
+  const normalized = normalizePath(basePath);
+  if (normalized === "/") return "";
+
+  return normalized;
+}
+
+function toSegments(pathname: string) {
+  return normalizePath(pathname).split("/").filter(Boolean);
+}
+
+function toPath(segments: string[]) {
+  if (segments.length === 0) return "";
+
+  return `/${segments.join("/")}`;
+}
+
+export function parsePresentationPath(pathname: string): ParsedPresentationPath | null {
+  const segments = toSegments(pathname);
+  if (segments.length === 0) return null;
+
+  const last = segments[segments.length - 1];
+  if (ROLE_SET.has(last as PresentationPathRole)) {
+    return {
+      role: last as PresentationPathRole,
+      slideNumber: null,
+      basePath: toPath(segments.slice(0, -1)),
+    };
+  }
+
+  const maybeSlideNumber = Number.parseInt(last, 10);
+  if (!Number.isNaN(maybeSlideNumber) && maybeSlideNumber > 0 && segments.length >= 2) {
+    const maybeRole = segments[segments.length - 2];
+    if (ROLE_SET.has(maybeRole as PresentationPathRole)) {
+      return {
+        role: maybeRole as PresentationPathRole,
+        slideNumber: maybeSlideNumber,
+        basePath: toPath(segments.slice(0, -2)),
+      };
+    }
+  }
+
+  return null;
+}
+
+export function parseStandalonePath(pathname: string): ParsedStandalonePath | null {
+  const parsedPresentation = parsePresentationPath(pathname);
+  if (parsedPresentation) return null;
+
+  const segments = toSegments(pathname);
+  if (segments.length === 0) return null;
+
+  const maybeSlideNumber = Number.parseInt(segments[segments.length - 1], 10);
+  if (Number.isNaN(maybeSlideNumber) || maybeSlideNumber < 1) return null;
+
+  return {
+    slideNumber: maybeSlideNumber,
+    basePath: toPath(segments.slice(0, -1)),
+  };
+}
+
+export function resolvePresentationBasePath(pathname: string) {
+  const parsed = parsePresentationPath(pathname);
+  if (parsed) return normalizeBasePath(parsed.basePath);
+
+  const parsedStandalone = parseStandalonePath(pathname);
+  if (parsedStandalone) return normalizeBasePath(parsedStandalone.basePath);
+
+  const normalized = normalizePath(pathname);
+  if (normalized === "/") return "";
+
+  if (normalized === "/index.html") return "";
+
+  if (normalized.endsWith("/index.html"))
+    return normalizeBasePath(normalized.slice(0, -"/index.html".length));
+
+  return normalizeBasePath(normalized);
+}
+
+export function buildRolePathFromBase(
+  basePath: string,
+  role: PresentationPathRole,
+  slideNumber: number,
+) {
+  const normalizedBase = normalizeBasePath(basePath);
+  const safeSlideNumber =
+    Number.isFinite(slideNumber) && slideNumber > 0 ? Math.floor(slideNumber) : 1;
+
+  if (!normalizedBase) return `/${role}/${safeSlideNumber}`;
+
+  return `${normalizedBase}/${role}/${safeSlideNumber}`;
+}
+
+export function buildRolePathFromPathname(
+  pathname: string,
+  role: PresentationPathRole,
+  slideNumber: number,
+) {
+  return buildRolePathFromBase(resolvePresentationBasePath(pathname), role, slideNumber);
+}
+
+export function buildStandalonePathFromBase(basePath: string, slideNumber: number) {
+  const normalizedBase = normalizeBasePath(basePath);
+  const safeSlideNumber =
+    Number.isFinite(slideNumber) && slideNumber > 0 ? Math.floor(slideNumber) : 1;
+
+  if (!normalizedBase) return `/${safeSlideNumber}`;
+
+  return `${normalizedBase}/${safeSlideNumber}`;
+}
+
+export function buildStandalonePathFromPathname(pathname: string, slideNumber: number) {
+  return buildStandalonePathFromBase(resolvePresentationBasePath(pathname), slideNumber);
+}