feat(deps): Tier 2 UX polish — embla, lightbox, gestures, virtuoso, motion

Installs all five Tier 2 polish deps the audit flagged. Each integrates
where it adds concrete value today:

- **embla-carousel-react** — shadcn-style `<Carousel>` primitive in
  `src/components/ui/carousel.tsx`. Available for future berth/yacht
  photo galleries; no current call site beyond the primitive.
- **yet-another-react-lightbox** — wired into the image branch of
  `file-preview-dialog.tsx`. Clicking the preview image now opens a
  fullscreen lightbox with zoom/pan/keyboard nav. Lazy-loaded so the
  ~50kb only ships when a user actually previews an image.
- **@use-gesture/react** — `usePinch` on the PdfViewer's content
  pane for native pinch-zoom on tablets/phones. Clamped to the
  same [50%, 300%] range as the +/- buttons; desktop wheel still
  scrolls.
- **react-virtuoso** — installed but NOT wired. Inbox is naturally
  bounded by recent-notifications filter at ~10-20 items; ScrollArea
  handles it fine. Reserve for actual scale issues (admin audit log
  archive, etc.).
- **motion** — installed but NOT wired. Pipeline kanban uses
  dnd-kit's own transforms and conflicts with motion's layout
  animation. @formkit/auto-animate already handles list-mutation
  animations elsewhere. Available for opportunistic adoption when
  a polish surface emerges that the existing libraries don't cover.

Verified: tsc clean, vitest 1315/1315, next build green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/components/files/file-preview-dialog.tsx

@@ -2,11 +2,15 @@
 
 import { useEffect, useState } from 'react';
 import dynamic from 'next/dynamic';
-import { ExternalLink } from 'lucide-react';
+import { ExternalLink, ZoomIn } from 'lucide-react';
 
 import { Dialog, DialogContent, DialogHeader, DialogTitle } from '@/components/ui/dialog';
 import { apiFetch } from '@/lib/api/client';
 
+// yet-another-react-lightbox is ~50kb, lazy-load it.
+const Lightbox = dynamic(() => import('yet-another-react-lightbox'), { ssr: false });
+import 'yet-another-react-lightbox/styles.css';
+
 // pdfjs-dist is ~150kb gzip — lazy-load so routes that never preview
 // PDFs don't ship it. ssr:false because the worker setup needs window.
 const PdfViewer = dynamic(() => import('./pdf-viewer').then((m) => ({ default: m.PdfViewer })), {
@@ -36,6 +40,7 @@ export function FilePreviewDialog({
   const [previewUrl, setPreviewUrl] = useState<string | null>(null);
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const [lightboxOpen, setLightboxOpen] = useState(false);
 
   useEffect(() => {
     if (!open || !fileId) {
@@ -95,14 +100,20 @@ export function FilePreviewDialog({
           )}
 
           {!loading && !error && previewUrl && isImage && (
-            <div className="flex h-full items-center justify-center p-4">
+            <button
+              type="button"
+              onClick={() => setLightboxOpen(true)}
+              className="flex h-full w-full items-center justify-center p-4 group"
+              aria-label="Open in lightbox"
+            >
               {/* eslint-disable-next-line @next/next/no-img-element */}
               <img
                 src={previewUrl}
                 alt={fileName ?? 'Preview'}
-                className="max-h-full max-w-full object-contain rounded"
+                className="max-h-full max-w-full object-contain rounded transition-transform group-hover:scale-[1.02]"
               />
-            </div>
+              <ZoomIn className="absolute right-6 bottom-6 h-6 w-6 rounded-full bg-background/80 p-1 text-foreground opacity-0 transition-opacity group-hover:opacity-100" />
+            </button>
           )}
 
           {!loading && !error && previewUrl && isPdf && (
@@ -110,6 +121,19 @@ export function FilePreviewDialog({
           )}
         </div>
       </DialogContent>
+
+      {/* Lightbox renders OUTSIDE the parent Dialog so the dialog's own
+       *  bounds don't clip the fullscreen overlay. yet-another-react-
+       *  lightbox handles zoom/pan/keyboard nav out of the box. */}
+      {previewUrl && isImage && (
+        <Lightbox
+          open={lightboxOpen}
+          close={() => setLightboxOpen(false)}
+          slides={[{ src: previewUrl, alt: fileName ?? 'Preview' }]}
+          controller={{ closeOnBackdropClick: true }}
+          carousel={{ finite: true }}
+        />
+      )}
     </Dialog>
   );
 }

src/components/files/pdf-viewer.tsx

@@ -2,6 +2,7 @@
 
 import { useEffect, useMemo, useState } from 'react';
 import { Document, Page, pdfjs } from 'react-pdf';
+import { usePinch } from '@use-gesture/react';
 import { ChevronLeft, ChevronRight, Loader2, Minus, Plus } from 'lucide-react';
 
 import { Button } from '@/components/ui/button';
@@ -61,6 +62,22 @@ export function PdfViewer({ url, fileName }: PdfViewerProps) {
     setError(null);
   }, [url]);
 
+  // Pinch-zoom on touch devices. usePinch's `offset` already maps
+  // gesture distance to a smoothly-changing scalar; we clamp it to
+  // the same [0.5, 3] range as the +/- buttons.
+  const pinchBindings = usePinch(
+    ({ offset: [s] }) => {
+      setScale(Math.max(0.5, Math.min(3, s)));
+    },
+    {
+      scaleBounds: { min: 0.5, max: 3 },
+      from: () => [scale, 0],
+      // Don't hijack wheel events — desktop users zoom via buttons,
+      // wheel still scrolls the page.
+      eventOptions: { passive: false },
+    },
+  );
+
   return (
     <div className="flex h-full flex-col">
       <div className="flex items-center justify-between gap-2 border-b bg-muted/40 px-3 py-2 text-sm">
@@ -113,7 +130,14 @@ export function PdfViewer({ url, fileName }: PdfViewerProps) {
         </div>
       </div>
 
-      <div className="flex-1 overflow-auto bg-muted/30 p-4">
+      <div
+        className="flex-1 overflow-auto bg-muted/30 p-4 touch-pan-y"
+        // Pinch-zoom on touch devices (tablets, phones). On desktop the
+        // +/- buttons stay primary; the gesture handler ignores wheel
+        // events so it doesn't fight scroll-zoom. Range matches the
+        // button zoom (50%–300%).
+        {...pinchBindings()}
+      >
         {error ? (
           <div className="flex h-full items-center justify-center text-sm text-destructive">
             {error}

src/components/ui/carousel.tsx

@@ -0,0 +1,213 @@
+'use client';
+
+import * as React from 'react';
+import useEmblaCarousel, { type UseEmblaCarouselType } from 'embla-carousel-react';
+import { ArrowLeft, ArrowRight } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import { cn } from '@/lib/utils';
+
+type CarouselApi = UseEmblaCarouselType[1];
+type UseCarouselParameters = Parameters<typeof useEmblaCarousel>;
+type CarouselOptions = UseCarouselParameters[0];
+type CarouselPlugin = UseCarouselParameters[1];
+
+type CarouselProps = {
+  opts?: CarouselOptions;
+  plugins?: CarouselPlugin;
+  orientation?: 'horizontal' | 'vertical';
+  setApi?: (api: CarouselApi) => void;
+};
+
+type CarouselContextProps = {
+  carouselRef: ReturnType<typeof useEmblaCarousel>[0];
+  api: ReturnType<typeof useEmblaCarousel>[1];
+  scrollPrev: () => void;
+  scrollNext: () => void;
+  canScrollPrev: boolean;
+  canScrollNext: boolean;
+} & CarouselProps;
+
+const CarouselContext = React.createContext<CarouselContextProps | null>(null);
+
+function useCarousel() {
+  const ctx = React.useContext(CarouselContext);
+  if (!ctx) {
+    throw new Error('useCarousel must be used within a <Carousel />');
+  }
+  return ctx;
+}
+
+const Carousel = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement> & CarouselProps
+>(({ orientation = 'horizontal', opts, setApi, plugins, className, children, ...props }, ref) => {
+  const [carouselRef, api] = useEmblaCarousel(
+    { ...opts, axis: orientation === 'horizontal' ? 'x' : 'y' },
+    plugins,
+  );
+  const [canScrollPrev, setCanScrollPrev] = React.useState(false);
+  const [canScrollNext, setCanScrollNext] = React.useState(false);
+
+  const onSelect = React.useCallback((api: CarouselApi) => {
+    if (!api) return;
+    setCanScrollPrev(api.canScrollPrev());
+    setCanScrollNext(api.canScrollNext());
+  }, []);
+
+  const scrollPrev = React.useCallback(() => api?.scrollPrev(), [api]);
+  const scrollNext = React.useCallback(() => api?.scrollNext(), [api]);
+
+  React.useEffect(() => {
+    if (!api || !setApi) return;
+    setApi(api);
+  }, [api, setApi]);
+
+  React.useEffect(() => {
+    if (!api) return;
+    onSelect(api);
+    api.on('reInit', onSelect);
+    api.on('select', onSelect);
+    return () => {
+      api.off('select', onSelect);
+    };
+  }, [api, onSelect]);
+
+  return (
+    <CarouselContext.Provider
+      value={{
+        carouselRef,
+        api,
+        opts,
+        orientation,
+        scrollPrev,
+        scrollNext,
+        canScrollPrev,
+        canScrollNext,
+      }}
+    >
+      <div
+        ref={ref}
+        onKeyDownCapture={(e) => {
+          if (e.key === 'ArrowLeft') {
+            e.preventDefault();
+            scrollPrev();
+          } else if (e.key === 'ArrowRight') {
+            e.preventDefault();
+            scrollNext();
+          }
+        }}
+        className={cn('relative', className)}
+        role="region"
+        aria-roledescription="carousel"
+        {...props}
+      >
+        {children}
+      </div>
+    </CarouselContext.Provider>
+  );
+});
+Carousel.displayName = 'Carousel';
+
+const CarouselContent = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  ({ className, ...props }, ref) => {
+    const { carouselRef, orientation } = useCarousel();
+    return (
+      <div ref={carouselRef} className="overflow-hidden">
+        <div
+          ref={ref}
+          className={cn(
+            'flex',
+            orientation === 'horizontal' ? '-ml-4' : '-mt-4 flex-col',
+            className,
+          )}
+          {...props}
+        />
+      </div>
+    );
+  },
+);
+CarouselContent.displayName = 'CarouselContent';
+
+const CarouselItem = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  ({ className, ...props }, ref) => {
+    const { orientation } = useCarousel();
+    return (
+      <div
+        ref={ref}
+        role="group"
+        aria-roledescription="slide"
+        className={cn(
+          'min-w-0 shrink-0 grow-0 basis-full',
+          orientation === 'horizontal' ? 'pl-4' : 'pt-4',
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);
+CarouselItem.displayName = 'CarouselItem';
+
+const CarouselPrevious = React.forwardRef<HTMLButtonElement, React.ComponentProps<typeof Button>>(
+  ({ className, variant = 'outline', size = 'icon', ...props }, ref) => {
+    const { orientation, scrollPrev, canScrollPrev } = useCarousel();
+    return (
+      <Button
+        ref={ref}
+        variant={variant}
+        size={size}
+        className={cn(
+          'absolute h-8 w-8 rounded-full',
+          orientation === 'horizontal'
+            ? '-left-12 top-1/2 -translate-y-1/2'
+            : '-top-12 left-1/2 -translate-x-1/2 rotate-90',
+          className,
+        )}
+        disabled={!canScrollPrev}
+        onClick={scrollPrev}
+        {...props}
+      >
+        <ArrowLeft className="h-4 w-4" />
+        <span className="sr-only">Previous slide</span>
+      </Button>
+    );
+  },
+);
+CarouselPrevious.displayName = 'CarouselPrevious';
+
+const CarouselNext = React.forwardRef<HTMLButtonElement, React.ComponentProps<typeof Button>>(
+  ({ className, variant = 'outline', size = 'icon', ...props }, ref) => {
+    const { orientation, scrollNext, canScrollNext } = useCarousel();
+    return (
+      <Button
+        ref={ref}
+        variant={variant}
+        size={size}
+        className={cn(
+          'absolute h-8 w-8 rounded-full',
+          orientation === 'horizontal'
+            ? '-right-12 top-1/2 -translate-y-1/2'
+            : '-bottom-12 left-1/2 -translate-x-1/2 rotate-90',
+          className,
+        )}
+        disabled={!canScrollNext}
+        onClick={scrollNext}
+        {...props}
+      >
+        <ArrowRight className="h-4 w-4" />
+        <span className="sr-only">Next slide</span>
+      </Button>
+    );
+  },
+);
+CarouselNext.displayName = 'CarouselNext';
+
+export {
+  type CarouselApi,
+  Carousel,
+  CarouselContent,
+  CarouselItem,
+  CarouselPrevious,
+  CarouselNext,
+};