@elabs-ai/components-viewer 4.0.0

package/src/core/zoom.ts

@@ -0,0 +1,56 @@
+/**
+ * The zoom vocabulary — the stops, and how the chrome moves between them.
+ *
+ * Lives in `core/` rather than in the PDF adapter (where the stops started)
+ * because zoom is now provider state: the shell's zoom control, the provider's
+ * `zoomIn`/`zoomOut` and every adapter that scales its content all have to agree
+ * on the same ladder, or "125%" in the toolbar and the scale the page rendered
+ * at drift apart.
+ */
+
+import type { ZoomFit, ZoomLevel } from "./types";
+
+/**
+ * Zoom stops, in document scale.
+ *
+ * Discrete rather than continuous: a slider is imprecise with a pointer and
+ * impossible with a keyboard at this size, and "somewhere near 137%" is not a
+ * state a reader ever wants to be in. The ladder is the one from the original
+ * PDF pager, unchanged, so existing screens land on the same numbers.
+ */
+export const VIEWER_ZOOM_STEPS = [0.5, 0.75, 1, 1.25, 1.5, 2, 3] as const;
+
+/** 100% — the scale a document opens at. */
+export const DEFAULT_ZOOM = 1;
+
+/** Float slack, so `1.0000000000000002 > 1` does not skip a stop. */
+const EPSILON = 1e-6;
+
+/** Whether a zoom level is a fit mode rather than a fixed scale. */
+export function isZoomFit(zoom: ZoomLevel): zoom is ZoomFit {
+  return typeof zoom === "string";
+}
+
+/**
+ * The next stop above or below `from`.
+ *
+ * Takes an arbitrary scale, not an index, because a fit mode resolves to
+ * whatever the viewport made it (1.37, say) and the reader's next "zoom in" has
+ * to land on a real stop above that — an index-based pager would jump back to
+ * wherever the ladder was last parked.
+ */
+export function stepZoom(from: number, delta: 1 | -1): number {
+  const steps = VIEWER_ZOOM_STEPS;
+  const first = steps[0];
+  const last = steps[steps.length - 1] as number;
+  if (delta === 1) return steps.find((step) => step > from + EPSILON) ?? last;
+  return [...steps].reverse().find((step) => step < from - EPSILON) ?? (first as number);
+}
+
+/** Whether there is a stop left in that direction — what disables the button. */
+export function canStepZoom(from: number, delta: 1 | -1): boolean {
+  const steps = VIEWER_ZOOM_STEPS;
+  return delta === 1
+    ? from < (steps[steps.length - 1] as number) - EPSILON
+    : from > (steps[0] as number) + EPSILON;
+}

package/src/file-viewer/file-viewer-context.tsx

@@ -0,0 +1,239 @@
+"use client";
+
+/**
+ * The context contract behind every `FileViewer` part.
+ *
+ * Per `component-api.md` ("Lift state into the Provider; expose a
+ * `state` / `actions` interface"), `FileViewerProvider` is the only thing that
+ * knows HOW a file is loaded. Parts read the interface below, so a sibling
+ * control placed outside the visual frame but inside the provider — a download
+ * button in a page header, a format badge in a breadcrumb — reads and drives the
+ * same state with no prop-drilling.
+ *
+ * This module is the CONTRACT only; the provider itself lives beside the parts
+ * it feeds, in `file-viewer.tsx`.
+ */
+
+import type { ProseHeadingLevel, ResolvedFileSource } from "@elabs-ai/components-ui";
+import { createContext, use } from "react";
+
+import type { ViewerError } from "../core/errors";
+import type { DocumentHighlight, HighlightSupport, ResolvedHighlight } from "../core/highlight";
+import type { ViewerRegistry } from "../core/registry";
+import type {
+  AdapterCapabilities,
+  AdapterDocument,
+  AdapterModule,
+  DocumentRotation,
+  ZoomLevel,
+} from "../core/types";
+
+/**
+ * Where a file is in its journey to the screen.
+ *
+ * `loading` means "no renderable content yet" — the canonical signal from
+ * `.claude/rules/loading-states.md`, rendered as a layout-shaped skeleton.
+ * There is no separate `isStreaming`: a file arrives settled or not at all.
+ */
+export type FileViewerStatus = "empty" | "loading" | "ready" | "error";
+
+/**
+ * The LOAD half of the state — everything the fetch-and-parse effect owns.
+ *
+ * Split from the highlight half because the two have different lifetimes: this
+ * one is replaced wholesale each time a file is opened, while the citations
+ * pointing into it are a prop the app controls and outlive any single parse.
+ * Folding them together would mean every `setState` in the load effect had to
+ * remember to carry the highlights forward.
+ */
+export interface FileViewerLoadState {
+  status: FileViewerStatus;
+  /** The resolved source, available as soon as there IS one — before any read. */
+  source?: ResolvedFileSource;
+  /** The adapter's parsed output. Only in `ready`. */
+  document?: AdapterDocument;
+  /** The adapter module that produced it, for its `Renderer`. Only in `ready`. */
+  adapter?: AdapterModule;
+  /** What the chrome may offer. Known from the manifest BEFORE the parser loads. */
+  capabilities: AdapterCapabilities;
+  /** Only in `error`. Always a `ViewerError`, so `code` can drive the message. */
+  error?: ViewerError;
+}
+
+/**
+ * How the open document is being LOOKED at — which page, at what scale, turned
+ * which way.
+ *
+ * Separate from the load state because it survives nothing and owns nothing: it
+ * is pure view, reset (page, rotation) or carried (zoom) when a new file opens.
+ * It lives in the provider rather than inside each adapter's `Renderer` so a
+ * control can sit anywhere — the shell toolbar, an app's own page header, a
+ * deep link — instead of only inside the canvas (ADR 0026).
+ */
+export interface FileViewerViewState {
+  /** 1-based. `1` for a format that does not paginate. */
+  pageNumber: number;
+  /** `0` until a paginated document is ready, and for formats with no pages. */
+  pageCount: number;
+  /** What was ASKED for: a fixed scale, or a fit mode the renderer resolves. */
+  zoom: ZoomLevel;
+  /**
+   * What that resolved to, as a number — what the zoom control shows and what
+   * `zoomIn`/`zoomOut` step from. Equal to `zoom` whenever `zoom` is a number.
+   */
+  effectiveZoom: number;
+  /** Quarter-turns clockwise. Reset to `0` when a different file is opened. */
+  rotation: DocumentRotation;
+}
+
+export interface FileViewerState extends FileViewerLoadState, FileViewerViewState {
+  /**
+   * The parts of the document to point at, as REQUESTED. What was actually
+   * located is `meta.resolvedHighlights` — the request survives a miss so the
+   * chrome can say "we couldn't find that passage" instead of showing nothing.
+   */
+  highlights: readonly DocumentHighlight[];
+  /** Which one the viewer is pointed at. `null` is "none", explicitly. */
+  activeHighlightId: string | null;
+  find: FileViewerFindState;
+}
+
+/** What find-in-document is doing right now. */
+export interface FileViewerFindState {
+  /** Whether the search box is showing. */
+  open: boolean;
+  query: string;
+  caseSensitive: boolean;
+  /** How many matches the current query has. */
+  matches: number;
+  /** Whether that count hit `FIND_MATCH_LIMIT` and is therefore a floor. */
+  truncated: boolean;
+  /**
+   * Which match is current, 0-based — the "3" in "3 of 12", minus one.
+   *
+   * Deliberately NOT the same knob as `activeHighlightId`. Find is the viewer's
+   * own, and an app that controls `activeHighlightId` to drive citations would
+   * otherwise have to also honour every keystroke of a search it never asked
+   * for, or silently break next/previous.
+   */
+  activeIndex: number;
+}
+
+export interface FileViewerActions {
+  /** Re-run the load. The retry action on the error state. */
+  reload: () => void;
+  /**
+   * Replace the citations. While `highlights` is controlled this writes no local
+   * state — but it still calls `onHighlightsChange`, so the owner can accept the
+   * request. Mirroring the platform: a controlled input reports, it does not
+   * self-update.
+   */
+  setHighlights: (highlights: readonly DocumentHighlight[]) => void;
+  /** Point the viewer at one highlight, or at none. */
+  setActiveHighlight: (id: string | null) => void;
+  /** Move to the next/previous CITATION in document order, wrapping around. */
+  nextHighlight: () => void;
+  previousHighlight: () => void;
+  openFind: () => void;
+  closeFind: () => void;
+  setFindQuery: (query: string) => void;
+  setFindCaseSensitive: (caseSensitive: boolean) => void;
+  /** Move to the next/previous SEARCH match, wrapping around. */
+  nextFindMatch: () => void;
+  previousFindMatch: () => void;
+  /**
+   * Turn to a page, 1-based. Clamped to the document — an out-of-range page is
+   * a caller's arithmetic slip, not a reason to blank the canvas.
+   */
+  goToPage: (page: number) => void;
+  /** Turn one page. Both stop at the ends rather than wrapping: a document is not a carousel. */
+  nextPage: () => void;
+  previousPage: () => void;
+  /** Draw at a fixed scale, or hand the renderer a fit mode to resolve. */
+  setZoom: (zoom: ZoomLevel) => void;
+  /**
+   * Step to the next stop above/below what is currently ON SCREEN — so zooming
+   * in from a fitted page continues from the fitted scale, not from wherever the
+   * fixed ladder was last parked.
+   */
+  zoomIn: () => void;
+  zoomOut: () => void;
+  setRotation: (rotation: DocumentRotation) => void;
+  /** Turn the document a quarter-turn: `1` clockwise, `-1` counter-clockwise. */
+  rotate: (quarterTurns: 1 | -1) => void;
+  /**
+   * The renderer's report channel for {@link FileViewerViewState.effectiveZoom}
+   * — not for app code. `FileViewerContent` wires it to the adapter's
+   * `onZoomResolved`, the same way `registerFind` is wired to a part rather than
+   * called by a consumer.
+   */
+  reportZoom: (scale: number) => void;
+  /**
+   * Tell the viewer a find part is mounted; call the returned function on
+   * unmount. `FileViewerFind` does this for you — it exists so the frame knows
+   * whether taking Ctrl/Cmd+F off the browser leads anywhere.
+   */
+  registerFind: () => () => void;
+}
+
+export interface FileViewerContextValue {
+  state: FileViewerState;
+  actions: FileViewerActions;
+  registry: ViewerRegistry;
+  meta: {
+    /**
+     * The rung a viewed document's own top-level heading renders at. Passed to
+     * every adapter `Renderer`; see `AdapterRendererProps.baseHeadingLevel`.
+     */
+    baseHeadingLevel: ProseHeadingLevel;
+    /**
+     * Citations and find matches, LOCATED, in document order, numbered — what
+     * an adapter `Renderer` is handed and what the chrome counts.
+     */
+    resolvedHighlights: readonly ResolvedHighlight[];
+    /**
+     * Which highlight the viewer is EFFECTIVELY pointed at, and what an adapter
+     * `Renderer` receives as `activeHighlightId`.
+     *
+     * Not the same knob as `state.activeHighlightId`: that one is the citation
+     * the app controls, while the reader stepping through find matches is also
+     * "current". Find outranks the citation while its box is open and matching,
+     * so navigation and scrolling follow whichever the reader is actually moving.
+     */
+    currentHighlightId: string | null;
+    /** Which address kinds this document's adapter declared it can paint. */
+    highlightSupport: HighlightSupport;
+    /**
+     * Whether find-in-document applies to the open document. Derived, not read
+     * straight off the manifest — see `AdapterCapabilities.search`.
+     */
+    canFind: boolean;
+    /**
+     * Whether a `FileViewerFind` part is composed into this viewer.
+     *
+     * Separate from {@link canFind}, which only says the ADAPTER could paint a
+     * match. The frame needs both before it takes Ctrl/Cmd+F away from the
+     * browser: intercepting the shortcut with nowhere to type leaves a keyboard
+     * reader with no find at all.
+     */
+    hasFind: boolean;
+  };
+}
+
+/**
+ * Exported for `FileViewerProvider` (which lives with the parts it feeds, in
+ * `file-viewer.tsx`) — NOT part of the package's public surface.
+ */
+export const FileViewerContext = createContext<FileViewerContextValue | null>(null);
+
+/**
+ * Read the viewer state. Throws outside a provider — a part that silently
+ * rendered nothing would be far harder to diagnose than a named error.
+ */
+export function useFileViewer(): FileViewerContextValue {
+  const value = use(FileViewerContext);
+  if (!value) {
+    throw new Error("useFileViewer must be used inside a <FileViewerProvider> (or <FileViewer>).");
+  }
+  return value;
+}

package/src/file-viewer/file-viewer-find.tsx

@@ -0,0 +1,204 @@
+"use client";
+
+/**
+ * Find-in-document — the viewer's own Ctrl/Cmd+F.
+ *
+ * It paints through the SAME highlight layer citations use (`source: "search"`),
+ * so a document never grows two mark systems that disagree about what a mark
+ * looks like. Only which one is CURRENT differs, and that lives on its own knob
+ * (`find.activeIndex`) so an app controlling citations does not have to honour
+ * every keystroke of a search it never asked for.
+ *
+ * **Not a `role="toolbar"`.** A toolbar is one tab stop with roving arrow keys,
+ * and an `<input>` inside one has its Left/Right stolen from the caret. This is
+ * `role="search"` — the same call `FileViewerToolbar` already made.
+ */
+
+import {
+  cn,
+  IconButton,
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupInput,
+  Separator,
+  useLocale,
+} from "@elabs-ai/components-ui";
+import { CaseSensitiveIcon, ChevronDownIcon, ChevronUpIcon, SearchIcon, XIcon } from "lucide-react";
+import {
+  forwardRef,
+  useEffect,
+  useRef,
+  type HTMLAttributes,
+  type KeyboardEvent as ReactKeyboardEvent,
+} from "react";
+
+import { FIND_MATCH_LIMIT } from "../core/highlight";
+import { useFileViewer } from "./file-viewer-context";
+
+/** Whether a keyboard event is the platform's find shortcut. */
+export function isFindShortcut(event: {
+  key: string;
+  metaKey: boolean;
+  ctrlKey: boolean;
+}): boolean {
+  // Either modifier, not `navigator.platform`: a Mac driven by an external PC
+  // keyboard sends Ctrl, and sniffing the platform gets that reader wrong.
+  return event.key.toLowerCase() === "f" && (event.metaKey || event.ctrlKey);
+}
+
+export type FileViewerFindProps = HTMLAttributes<HTMLDivElement>;
+
+/**
+ * The search row. Renders nothing until `actions.openFind()` (or Ctrl/Cmd+F on
+ * the frame) opens it, and nothing at all for a document whose adapter cannot
+ * paint a range — an affordance that could never highlight anything is worse
+ * than no affordance at all.
+ */
+export const FileViewerFind = forwardRef<HTMLDivElement, FileViewerFindProps>(
+  function FileViewerFind({ className, ...props }, ref) {
+    const { state, actions, meta } = useFileViewer();
+    const { t, formatNumber } = useLocale();
+    const input = useRef<HTMLInputElement>(null);
+    const find = state.find;
+    const open = find.open && meta.canFind;
+    const { registerFind } = actions;
+
+    // Announce that there IS somewhere to type. The frame only takes Ctrl/Cmd+F
+    // away from the browser once this has run — a shortcut swallowed with no box
+    // to show leaves a keyboard reader with no find at all. Registered on mount
+    // rather than when open, because the box is closed at exactly the moment the
+    // shortcut has to be decided.
+    useEffect(() => registerFind(), [registerFind]);
+
+    // A find box that does not take the caret sends the next keystroke to the
+    // document behind it — the one thing every reader expects not to happen.
+    useEffect(() => {
+      if (open) input.current?.focus();
+    }, [open]);
+
+    if (!open) return null;
+
+    const hasQuery = find.query.length > 0;
+    const hasMatches = find.matches > 0;
+
+    const onKeyDown = (event: ReactKeyboardEvent<HTMLInputElement>) => {
+      if (event.key === "Escape") {
+        event.preventDefault();
+        // Stopped here: an Escape meant for the find box must not also close a
+        // Dialog the viewer happens to be sitting in.
+        event.stopPropagation();
+        actions.closeFind();
+        return;
+      }
+      if (event.key === "Enter") {
+        event.preventDefault();
+        if (event.shiftKey) actions.previousFindMatch();
+        else actions.nextFindMatch();
+      }
+    };
+
+    return (
+      <div
+        ref={ref}
+        data-slot="file-viewer-find"
+        role="search"
+        aria-label={t("viewer.find.label")}
+        className={cn(
+          // The divider is the only cue between this row and the content below
+          // it — same fill, no elevation change (WCAG 1.4.11, strong rung).
+          "border-border-strong flex shrink-0 items-center gap-2 border-b px-3 py-2",
+          className,
+        )}
+        {...props}
+      >
+        <InputGroup className="h-8 max-w-72">
+          <InputGroupAddon>
+            <SearchIcon aria-hidden="true" />
+          </InputGroupAddon>
+          <InputGroupInput
+            ref={input}
+            // Not `type="search"`: the browser's own clear affordance is
+            // unlabelled and unthemeable, and this row already carries a close
+            // control that does something more useful.
+            type="text"
+            value={find.query}
+            aria-label={t("viewer.find.label")}
+            placeholder={t("viewer.find.placeholder")}
+            autoComplete="off"
+            spellCheck={false}
+            onChange={(event) => actions.setFindQuery(event.target.value)}
+            onKeyDown={onKeyDown}
+          />
+          <InputGroupAddon align="inline-end">
+            {/* A real toggle button, so the state is announced rather than
+                inferred from a colour change. */}
+            <InputGroupButton
+              size="icon-xs"
+              aria-pressed={find.caseSensitive}
+              aria-label={t("viewer.find.caseSensitive")}
+              title={t("viewer.find.caseSensitive")}
+              onClick={() => actions.setFindCaseSensitive(!find.caseSensitive)}
+            >
+              <CaseSensitiveIcon aria-hidden="true" />
+            </InputGroupButton>
+          </InputGroupAddon>
+        </InputGroup>
+
+        {/* ONE live region for the whole result state: "3 of 12" and "No
+            matches" replace each other rather than sitting side by side, so a
+            fruitless search never reads as "0 of 0". */}
+        <span
+          role="status"
+          aria-live="polite"
+          className="text-meta text-muted-foreground min-w-0 flex-1 truncate tabular-nums"
+        >
+          {!hasQuery
+            ? null
+            : hasMatches
+              ? t("viewer.find.count", {
+                  index: formatNumber(find.activeIndex + 1),
+                  total: formatNumber(Math.min(find.matches, FIND_MATCH_LIMIT)),
+                })
+              : t("viewer.find.none")}
+          {find.truncated
+            ? ` ${t("viewer.find.capped", {
+                limit: formatNumber(FIND_MATCH_LIMIT),
+                total: formatNumber(find.matches),
+              })}`
+            : null}
+        </span>
+
+        {/* `aria-disabled`, never the native attribute: a focused control that
+            becomes `disabled` is dropped from the focus order, so a reader who
+            tabbed to Next and then cleared the query would have focus silently
+            fall to <body>. The actions are the real guard — both no-op with no
+            matches (see interaction-guidelines.md). */}
+        <IconButton
+          variant="ghost"
+          size="icon-sm"
+          aria-disabled={!hasMatches}
+          label={t("viewer.find.previous")}
+          icon={<ChevronUpIcon aria-hidden="true" />}
+          onClick={actions.previousFindMatch}
+        />
+        <IconButton
+          variant="ghost"
+          size="icon-sm"
+          aria-disabled={!hasMatches}
+          label={t("viewer.find.next")}
+          icon={<ChevronDownIcon aria-hidden="true" />}
+          onClick={actions.nextFindMatch}
+        />
+        <Separator orientation="vertical" className="h-4" />
+        <IconButton
+          variant="ghost"
+          size="icon-sm"
+          label={t("viewer.find.close")}
+          icon={<XIcon aria-hidden="true" />}
+          onClick={actions.closeFind}
+        />
+      </div>
+    );
+  },
+);

package/src/file-viewer/file-viewer-pager.tsx

@@ -0,0 +1,120 @@
+"use client";
+
+/**
+ * `FileViewerPager` — previous / a page you can type into / next.
+ *
+ * A PART, not adapter chrome. The page lives in the provider (ADR 0026), so this
+ * row can sit in the viewer's own toolbar, in an app's page header, or beside a
+ * thumbnail rail, and every copy of it stays in step. While the page was
+ * `useState` inside `PdfRenderer` there could only ever be one pager, inside the
+ * canvas.
+ *
+ * ## Why this is not a `role="toolbar"`
+ *
+ * The role promises roving-tabindex arrow-key navigation, and the page field is
+ * a TEXT INPUT — ArrowLeft/ArrowRight there move the caret. A toolbar that
+ * swallowed them would make the number unusable to a keyboard reader, so this is
+ * a plain named group of ordinary tab stops: the same call `FileViewerToolbar`
+ * and `ViewToolbar` make, for the same reason.
+ */
+
+import { cn, IconButton, Input, useLocale } from "@elabs-ai/components-ui";
+import { ChevronLeftIcon, ChevronRightIcon } from "lucide-react";
+import { forwardRef, useState, type HTMLAttributes } from "react";
+
+import { useFileViewer } from "./file-viewer-context";
+
+export type FileViewerPagerProps = HTMLAttributes<HTMLDivElement>;
+
+export const FileViewerPager = forwardRef<HTMLDivElement, FileViewerPagerProps>(
+  function FileViewerPager({ className, ...props }, ref) {
+    const { state, actions } = useFileViewer();
+    const { t, formatNumber } = useLocale();
+
+    // The half-typed value, while the reader is typing it. `null` means "not
+    // editing", so the field follows the document the rest of the time — a
+    // citation that turns the page updates the number under the caret too.
+    const [draft, setDraft] = useState<string | null>(null);
+
+    const { pageNumber, pageCount } = state;
+
+    // No pages, or none known yet: render nothing rather than an inert "1 of 0".
+    // Chrome with nothing in it reads as a broken render (viewer-components.md).
+    if (!state.capabilities.pages || pageCount === 0) return null;
+
+    const commit = () => {
+      if (draft === null) return;
+      const parsed = Number.parseInt(draft, 10);
+      setDraft(null);
+      // A blank or nonsense entry is a reader changing their mind, not a
+      // navigation — snap back to where they are instead of jumping to page 1.
+      if (Number.isNaN(parsed)) return;
+      actions.goToPage(parsed);
+    };
+
+    return (
+      <div
+        ref={ref}
+        data-slot="file-viewer-pager"
+        role="group"
+        aria-label={t("viewer.pager.controls")}
+        className={cn("flex shrink-0 items-center gap-1", className)}
+        {...props}
+      >
+        <IconButton
+          variant="ghost"
+          size="icon-sm"
+          label={t("viewer.pager.previous")}
+          icon={<ChevronLeftIcon aria-hidden="true" />}
+          disabled={pageNumber <= 1}
+          onClick={actions.previousPage}
+        />
+        <Input
+          // Explicit: Radix's toolbar slot and several wrappers default an
+          // unset `type` to `"button"`, which would silently turn the field
+          // into a button the day this moves inside one.
+          type="text"
+          inputMode="numeric"
+          autoComplete="off"
+          spellCheck={false}
+          aria-label={t("viewer.pager.pageNumber")}
+          value={draft ?? String(pageNumber)}
+          onChange={(event) => setDraft(event.target.value)}
+          onBlur={commit}
+          onKeyDown={(event) => {
+            if (event.key === "Enter") {
+              event.preventDefault();
+              commit();
+            } else if (event.key === "Escape") {
+              // Abandon the edit without navigating; focus stays put, so the
+              // reader can try again without re-reaching the field.
+              setDraft(null);
+            }
+          }}
+          className="h-7 w-12 px-1 text-center tabular-nums"
+        />
+        <span className="text-meta text-muted-foreground whitespace-nowrap tabular-nums">
+          {t("viewer.pager.of", { total: formatNumber(pageCount) })}
+        </span>
+        <IconButton
+          variant="ghost"
+          size="icon-sm"
+          label={t("viewer.pager.next")}
+          icon={<ChevronRightIcon aria-hidden="true" />}
+          disabled={pageNumber >= pageCount}
+          onClick={actions.nextPage}
+        />
+        {/* Paging repaints a canvas, which announces nothing on its own, and the
+            field's own value change is not announced either. ONE live region for
+            the group carries the whole sentence — `loading-states.md`'s rule that
+            a region announces once, not per element. */}
+        <span role="status" aria-live="polite" className="sr-only">
+          {t("viewer.pager.status", {
+            page: formatNumber(pageNumber),
+            total: formatNumber(pageCount),
+          })}
+        </span>
+      </div>
+    );
+  },
+);