FileViewerSegmentLegend

SegmentLegend is the "key" surface over a page-segmented result (partition chunks or split subdocuments) — a compact map from color to label. It docks to a document surface in three flavors: a flush bar, a floating overlay card, or a vertical rail.

Hovering is a temporary preview. When nothing is hovered, currentPage derives the highlighted segment. Clicking a segment only asks the host to navigate; it does not persist category selection. Wire the legend to the same useSegmentInteraction object as a segment sidebar for a coordinated layout.

"use client";

import * as React from "react";

import { toSegments } from "@/lib/segments";
import { cn } from "@/lib/utils";
import {
  SegmentLegend,
  type SegmentLegendOrientation,
  type SegmentLegendSide,

In a split viewer

Docked to a split viewer over one ViT paper split result — the same legend placed three ways (a flush bar, a floating card, and a vertical rail). One shared interaction state dims the matching pages across every cell at once.

"use client";

import { LegendVariantsBlock } from "@/registry/new-york-v4/blocks/legend-variants-block";

// The legend on a real split viewer: one ViT paper split result rendered
// with all three placements — bar, floating, and a vertical rail — sharing one
// selection across every cell.
export function SegmentLegendSplit() {
  return (
    <div className="not-prose overflow-hidden rounded-xl border">

Installation

pnpmnpmyarnbun
Copy
pnpm dlx shadcn@latest add @retab/segment-legend

Usage

Reduce a partition or split result to Segment[] with toSegments, then render the legend against your own interaction state:

Copyimport { toSegments } from "@/lib/segments";
import { SegmentLegend } from "@/components/ui/segment-legend";
import { useSegmentInteraction } from "@/components/ui/use-segment-interaction";
 
// partition: [{ key, pages }]   split: [{ name, pages }]
const segments = toSegments(result.output);
 
export function Example() {
  const interaction = useSegmentInteraction();
  return (
    <SegmentLegend
      segments={segments}
      variant="bar"
      interaction={interaction}
      currentPage={1}
    />
  );
}

The floating variant needs a relative parent to anchor against; side controls which edge it docks to.

For caller-owned preview state, build the same interaction object with useControlledSegmentInteraction; do not pass selection props to the legend.

API Reference

Source

"use client";

import * as React from "react";

import {
  getSegmentInteractionState,
  getSegmentSurfaceProps,
  scopeSegmentInteraction,
  type SegmentInteraction,
} from "@/lib/segment-interaction";
import { segmentDisplayLabel, segmentPageCount } from "@/lib/segments";
import { cn } from "@/lib/utils";