Segment Legend

1"use client";
2 
3import * as React from "react";
4 
5import {
6  getSegmentInteractionState,
7  getSegmentSurfaceProps,
8  scopeSegmentInteraction,
9  type SegmentInteraction,
10} from "@/lib/segment-interaction";
11import { segmentDisplayLabel, segmentPageCount } from "@/lib/segments";
12import { cn } from "@/lib/utils";
13 
14import type { DocumentSegment } from "./segmented-document-model";
15 
16/** How the legend attaches to the document surface. */
17export type SegmentLegendVariant = "bar" | "floating" | "plain";
18export type SegmentLegendOrientation = "horizontal" | "vertical";
19export type SegmentLegendSide = "top" | "bottom" | "left" | "right";
20export type SegmentLegendDensity = "comfortable" | "compact";
21 
22export interface SegmentLegendProps {
23  segments: DocumentSegment[];
24  /**
25   * How the legend attaches to the document surface:
26   * - `bar` — flush, full-width, bordered on its docking side (default).
27   * - `floating` — an overlay card pinned to a corner; needs a `relative` parent.
28   * - `plain` — raw entries, no chrome (compose your own container).
29   * @default "bar"
30   */
31  variant?: SegmentLegendVariant;
32  /** Lay entries out horizontally (wrap/grid) or vertically (rail). @default "horizontal" */
33  orientation?: SegmentLegendOrientation;
34  /** Edge the legend docks to — drives the border (`bar`) or anchor (`floating`). */
35  side?: SegmentLegendSide;
36  /** Swatch + label scale. @default "comfortable" */
37  density?: SegmentLegendDensity;
38  /** Shared preview state. */
39  interaction?: SegmentInteraction;
40  /** Fired when a segment surface is clicked, after transient preview is cleared. */
41  onSelect?: (segment: DocumentSegment) => void;
42  /** 1-based current page; owning segments receive current-page styling. */
43  currentPage?: number | null;
44  /** Lay entries out on a grid of N columns instead of wrapping inline (horizontal only). */
45  columns?: number;
46  /** Render a "Show all / Hide unused" toggle when some segments own no pages. */
47  showUnusedToggle?: boolean;
48  /** Controlled visibility of zero-page segments. */
49  showUnused?: boolean;
50  /** Initial visibility of zero-page segments when `showUnused` is uncontrolled. */
51  defaultShowUnused?: boolean;
52  onShowUnusedChange?: (showUnused: boolean) => void;
53  /** A muted caption rendered under the entries (e.g. a classification's reasoning). */
54  caption?: React.ReactNode;
55  className?: string;
56}
57 
58const DENSITY = {
59  comfortable: { swatch: "h-3 w-5", text: "text-xs", gap: "gap-x-4 gap-y-1.5" },
60// … truncated