@opengeni/react 0.57.0 → 1.0.2-canary.37191796234001

package/src/components/timeline-anchor.tsx

@@ -0,0 +1,119 @@
+import { Component, type ReactNode } from "react";
+
+type Anchor = {
+  element: HTMLElement;
+  key: string | null;
+  text: string | null;
+  top: number;
+  focused?: boolean;
+};
+export type TimelineAnchor = Anchor[];
+
+/** Read ownership synchronously: selectionchange may follow the next React commit. */
+export function timelineHasReader(scroller: HTMLElement | null): boolean {
+  if (!scroller) return false;
+  const focused = scroller.ownerDocument.activeElement;
+  const selection = scroller.ownerDocument.getSelection();
+  return Boolean(
+    (focused && focused !== scroller && scroller.contains(focused)) ||
+    (selection &&
+      !selection.isCollapsed &&
+      (scroller.contains(selection.anchorNode) || scroller.contains(selection.focusNode))),
+  );
+}
+
+/** Read the old DOM immediately before React changes it, not when a fetch starts. */
+export class TimelineBeforeLayout extends Component<{
+  capture: () => void;
+  children: ReactNode;
+}> {
+  getSnapshotBeforeUpdate() {
+    this.props.capture();
+    return null;
+  }
+  componentDidUpdate() {}
+  render() {
+    return this.props.children;
+  }
+}
+
+export function captureTimelineAnchor(scroller: HTMLElement): TimelineAnchor | null {
+  const viewport = scroller.getBoundingClientRect();
+  if (viewport.height <= 0) return null;
+  // Capture each box once: these measurements share one pre-commit DOM snapshot.
+  const groups = Array.from(scroller.querySelectorAll<HTMLElement>("[data-og-group-key]"))
+    .map((element) => ({ element, rect: element.getBoundingClientRect() }))
+    .filter(({ rect }) => rect.height > 0);
+  const anchors: TimelineAnchor = [];
+  let stickyFocus: Anchor | undefined;
+  // A disclosure is the reader's explicit point of interaction. In particular,
+  // anchoring a paragraph below an expanding disclosure would move its button.
+  const focused = scroller.ownerDocument.activeElement;
+  if (focused instanceof HTMLElement && scroller.contains(focused) && focused !== scroller) {
+    const box = focused.getBoundingClientRect();
+    if (box.bottom > viewport.top && box.top < viewport.bottom) {
+      const anchor = { element: focused, key: null, text: null, top: box.top, focused: true };
+      const section = focused.closest("[data-og-work-section]");
+      // A stuck header stays put even when its section moves. Anchor the work
+      // being read beneath it instead, while still retaining its focus identity.
+      if (
+        focused.matches('[data-og-work-header="outer"]') &&
+        section &&
+        section.getBoundingClientRect().top < box.top - 1
+      )
+        stickyFocus = anchor;
+      else anchors.push(anchor);
+    }
+  }
+  // A paragraph survives even when earlier deltas reconstruct its containing message.
+  for (const { element: group, rect } of groups) {
+    if (rect.bottom <= viewport.top || rect.top >= viewport.bottom) continue;
+    for (const element of group.querySelectorAll<HTMLElement>("p, li, pre, h1, h2, h3, h4")) {
+      const box = element.getBoundingClientRect();
+      const text = element.textContent;
+      if (box.bottom > viewport.top && box.top < viewport.bottom && text && text.length >= 12) {
+        anchors.push({ element, key: null, text, top: box.top });
+      }
+    }
+  }
+  // Prefer a retained visible row, then a following row. A following row also
+  // anchors the unchanged suffix of a partially loaded message above it.
+  const rows = groups.map(({ element, rect }) => ({
+    element,
+    key: element.getAttribute("data-og-group-key"),
+    text: null,
+    top: rect.top,
+  }));
+  anchors.push(...rows.filter((row) => row.top >= viewport.top));
+  anchors.push(...rows.filter((row) => row.top < viewport.top).reverse());
+  if (stickyFocus) anchors.push(stickyFocus);
+  return anchors;
+}
+
+/** Return only the correction native browser anchoring has not already made. */
+export function timelineAnchorCorrection(
+  scroller: HTMLElement,
+  anchors: TimelineAnchor,
+): number | null {
+  let blocks: HTMLElement[] | undefined;
+  let groups: HTMLElement[] | undefined;
+  for (const anchor of anchors) {
+    let element: HTMLElement | undefined;
+    if (
+      scroller.contains(anchor.element) &&
+      (!anchor.text || anchor.element.textContent === anchor.text)
+    ) {
+      element = anchor.element;
+    } else if (anchor.key) {
+      groups ??= Array.from(scroller.querySelectorAll<HTMLElement>("[data-og-group-key]"));
+      element = groups.find((group) => group.getAttribute("data-og-group-key") === anchor.key);
+    } else if (anchor.text) {
+      blocks ??= Array.from(scroller.querySelectorAll<HTMLElement>("p, li, pre, h1, h2, h3, h4"));
+      const matches = blocks.filter((block) => block.textContent === anchor.text);
+      // Repeated boilerplate is not sufficient evidence of retained content.
+      if (matches.length === 1) element = matches[0];
+    }
+    if (element) return element.getBoundingClientRect().top - anchor.top;
+  }
+  return null;
+}

package/src/components/timeline-annotation-chrome.tsx

@@ -0,0 +1,196 @@
+import type {
+  DraftTimelineAnnotation,
+  TimelineAnnotation,
+  TimelineAnnotationSource,
+} from "@opengeni/sdk";
+import { useLayoutEffect, useRef, useState, type ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { annotationNoteNeedsDisclosure } from "./timeline-annotation-layout";
+import { useTimelineAnnotationSourceRoot } from "./timeline-annotation-reveal-context";
+import {
+  annotationSourceLabel,
+  revealLoadedAnnotationSource,
+  truncateAnnotationQuote,
+} from "./timeline-annotation-shared";
+
+export type TimelineAnnotationLike = DraftTimelineAnnotation | TimelineAnnotation;
+
+const NOTE_MAX_HEIGHT_PX = 160;
+
+function autosizeNote(textarea: HTMLTextAreaElement | null): void {
+  if (!textarea) return;
+  textarea.style.height = "auto";
+  textarea.style.height = `${Math.min(Math.max(textarea.scrollHeight, 32), NOTE_MAX_HEIGHT_PX)}px`;
+}
+
+function quotePreview(quote: string): { text: string; multiline: boolean } {
+  const trimmed = quote.trim();
+  const multiline = trimmed.includes("\n");
+  return {
+    text: multiline ? trimmed : trimmed.replace(/\s+/g, " "),
+    multiline,
+  };
+}
+
+export function AnnotationQuoteSourceButton({
+  annotation,
+  lines = 2,
+  onRevealSource,
+  onUnavailable,
+}: {
+  annotation: TimelineAnnotationLike;
+  lines?: 2 | 3;
+  onRevealSource?: ((source: TimelineAnnotationSource) => boolean) | undefined;
+  onUnavailable: (id: string | null) => void;
+}) {
+  const preview = quotePreview(annotation.quote);
+  const sourceLabel = annotationSourceLabel(annotation.source);
+  const sourceRoot = useTimelineAnnotationSourceRoot();
+  return (
+    <button
+      type="button"
+      title={annotation.quote}
+      aria-label={`View ${sourceLabel} source: ${truncateAnnotationQuote(annotation.quote, 88)}`}
+      className="block w-full min-w-0 rounded-sm border-0 bg-transparent text-left text-og-sm leading-5 text-og-fg-muted outline-hidden transition-colors hover:text-og-fg focus-visible:ring-2 focus-visible:ring-og-accent pointer-coarse:min-h-[44px]"
+      onClick={() => {
+        const revealed =
+          onRevealSource?.(annotation.source) ??
+          (sourceRoot
+            ? revealLoadedAnnotationSource(annotation.source, sourceRoot.current)
+            : revealLoadedAnnotationSource(annotation.source));
+        onUnavailable(revealed ? null : annotation.id);
+      }}
+    >
+      <span
+        className={cn(
+          "block min-w-0 max-w-full break-words",
+          preview.multiline ? "whitespace-pre-wrap" : "whitespace-normal",
+          lines === 3 ? "line-clamp-3" : "line-clamp-2",
+        )}
+      >
+        {preview.text}
+      </span>
+      <span className="sr-only"> view source</span>
+    </button>
+  );
+}
+
+export function AnnotationAccentRow({
+  children,
+  className,
+}: {
+  children: ReactNode;
+  className?: string | undefined;
+}) {
+  return (
+    <div className={cn("flex gap-2.5", className)}>
+      <div aria-hidden="true" className="w-0.5 shrink-0 rounded-full bg-og-accent/55" />
+      <div className="min-w-0 flex-1">{children}</div>
+    </div>
+  );
+}
+
+export function AnnotationNotePreview({
+  note,
+  annotationId,
+  ordinal,
+  className,
+}: {
+  note: string;
+  annotationId: string;
+  ordinal: number;
+  className?: string | undefined;
+}) {
+  const [expanded, setExpanded] = useState(false);
+  if (!note) return null;
+  const collapsible = annotationNoteNeedsDisclosure(note);
+  const contentId = `og-annotation-note-${annotationId}`;
+  return (
+    <div className={className}>
+      <p
+        id={contentId}
+        data-og-annotation-note=""
+        data-og-annotation-note-expanded={expanded ? "true" : "false"}
+        className={cn(
+          "mt-0.5 break-words whitespace-pre-wrap text-og-sm leading-5 text-og-fg",
+          !expanded && "line-clamp-4",
+        )}
+      >
+        {note}
+      </p>
+      {collapsible ? (
+        <button
+          type="button"
+          className="mt-0.5 inline-flex min-h-7 items-center rounded-og-sm px-1 text-og-xs font-medium text-og-fg-muted outline-hidden hover:text-og-fg focus-visible:ring-2 focus-visible:ring-og-accent pointer-coarse:min-h-11"
+          aria-expanded={expanded}
+          aria-controls={contentId}
+          aria-label={
+            expanded ? `Show less annotation ${ordinal}` : `Show more annotation ${ordinal}`
+          }
+          onClick={() => setExpanded((current) => !current)}
+        >
+          {expanded ? "Show less" : "Show more"}
+        </button>
+      ) : null}
+    </div>
+  );
+}
+
+export function AnnotationNoteField({
+  annotation,
+  inputRef,
+  onUpdate,
+  onCommit,
+}: {
+  annotation: TimelineAnnotationLike;
+  inputRef?: ((node: HTMLTextAreaElement | null) => void) | undefined;
+  onUpdate: (id: string, note: string) => void;
+  onCommit?: (() => void) | undefined;
+}) {
+  const localRef = useRef<HTMLTextAreaElement | null>(null);
+  const setRef = (node: HTMLTextAreaElement | null) => {
+    localRef.current = node;
+    inputRef?.(node);
+  };
+
+  useLayoutEffect(() => {
+    const textarea = localRef.current;
+    if (!textarea) return;
+    // Ref callbacks can reattach on every scroll-driven parent render. Reflowing
+    // unchanged notes there interrupts native scrolling, particularly in WebKit.
+    autosizeNote(textarea);
+    if (typeof ResizeObserver === "undefined") return;
+    let width = textarea.getBoundingClientRect().width;
+    const observer = new ResizeObserver(() => {
+      const nextWidth = textarea.getBoundingClientRect().width;
+      if (nextWidth === width) return;
+      width = nextWidth;
+      autosizeNote(textarea);
+    });
+    observer.observe(textarea);
+    return () => observer.disconnect();
+  }, [annotation.note]);
+
+  return (
+    <textarea
+      ref={setRef}
+      value={annotation.note}
+      rows={1}
+      maxLength={2048}
+      placeholder="Add a note…"
+      aria-label="Note"
+      className="mt-0.5 max-h-40 min-h-8 w-full resize-none overflow-y-auto break-words border-0 bg-transparent px-0 py-1 text-og-sm leading-5 text-og-fg outline-hidden placeholder:text-og-fg-subtle focus-visible:ring-0"
+      onInput={(event) => {
+        autosizeNote(event.currentTarget);
+        onUpdate(annotation.id, event.currentTarget.value);
+      }}
+      onKeyDown={(event) => {
+        if (event.key !== "Enter" || event.shiftKey || event.nativeEvent.isComposing) return;
+        event.preventDefault();
+        event.stopPropagation();
+        if (event.currentTarget.value.trim().length === 0) return;
+        onCommit?.();
+      }}
+    />
+  );
+}

package/src/components/timeline-annotation-layout.ts

@@ -0,0 +1,268 @@
+export type AnnotationBox = {
+  left: number;
+  right: number;
+  top: number;
+  bottom: number;
+};
+
+export type AnnotationBadgeAnchor = {
+  id: string;
+  ordinal: number;
+  left: number;
+  top: number;
+  incomplete: boolean;
+};
+
+export const ANNOTATION_BADGE_GAP_PX = 32;
+export const ANNOTATION_BADGE_MIN_GAP_PX = 12;
+export const ANNOTATION_REVIEW_DIALOG_WIDTH_PX = 400;
+export const ANNOTATION_REVIEW_DIALOG_MAX_HEIGHT_PX = 32 * 16;
+export const ANNOTATION_REVIEW_DIALOG_MIN_HEIGHT_PX = 160;
+export const ANNOTATION_REVIEW_DIALOG_FLOOR_HEIGHT_PX = 80;
+export const ANNOTATION_REVIEW_MARGIN_PX = 12;
+export const ANNOTATION_NOTE_PREVIEW_CHARS = 280;
+export const ANNOTATION_CARD_STACK_SCROLL_AT = 4;
+
+function clampAnnotationAxis(value: number, min: number, max: number): number {
+  return Math.min(Math.max(value, min), Math.max(min, max));
+}
+
+export function annotationBoxIntersects(a: AnnotationBox, b: AnnotationBox): boolean {
+  return a.left <= b.right && a.right >= b.left && a.top <= b.bottom && a.bottom >= b.top;
+}
+
+export function annotationViewportBox(
+  viewportWidth: number,
+  viewportHeight: number,
+  scroller?: AnnotationBox | null,
+): AnnotationBox {
+  const viewport: AnnotationBox = {
+    left: 0,
+    top: 0,
+    right: Math.max(1, viewportWidth),
+    bottom: Math.max(1, viewportHeight),
+  };
+  if (!scroller || scroller.right - scroller.left <= 0 || scroller.bottom - scroller.top <= 0) {
+    return viewport;
+  }
+  return {
+    left: Math.max(viewport.left, scroller.left),
+    top: Math.max(viewport.top, scroller.top),
+    right: Math.min(viewport.right, scroller.right),
+    bottom: Math.min(viewport.bottom, scroller.bottom),
+  };
+}
+
+export function annotationNoteNeedsDisclosure(note: string): boolean {
+  const trimmed = note.trim();
+  if (trimmed.length === 0) return false;
+  return trimmed.length > ANNOTATION_NOTE_PREVIEW_CHARS || trimmed.split("\n").length > 4;
+}
+
+function annotationAxisStops(min: number, max: number, gap: number): number[] {
+  if (max <= min) return [min];
+  const stops: number[] = [];
+  for (let value = min; value <= max + 1e-6; value += gap) {
+    stops.push(value);
+  }
+  return stops;
+}
+
+function annotationPointKey(left: number, top: number): string {
+  return `${Math.round(left * 100) / 100},${Math.round(top * 100) / 100}`;
+}
+
+function annotationPointFree(
+  left: number,
+  top: number,
+  placed: readonly AnnotationBadgeAnchor[],
+  gap: number,
+): boolean {
+  return placed.every((other) => Math.hypot(left - other.left, top - other.top) >= gap);
+}
+
+export function annotationBadgePackGap(
+  viewport: AnnotationBox,
+  count: number,
+  preferred = ANNOTATION_BADGE_GAP_PX,
+): number {
+  if (count <= 1) return preferred;
+  const width = Math.max(
+    1,
+    viewport.right - ANNOTATION_REVIEW_MARGIN_PX - (viewport.left + ANNOTATION_REVIEW_MARGIN_PX),
+  );
+  const height = Math.max(1, viewport.bottom - ANNOTATION_REVIEW_MARGIN_PX - (viewport.top + 8));
+  let gap = preferred;
+  const capacity = (step: number) =>
+    (Math.floor(width / step) + 1) * (Math.floor(height / step) + 1);
+  while (gap > ANNOTATION_BADGE_MIN_GAP_PX && capacity(gap) < count) {
+    gap -= 1;
+  }
+  return gap;
+}
+
+const ANNOTATION_BADGE_SHIFT_DIRS: Array<[number, number]> = [
+  [1, 0],
+  [1, 1],
+  [0, 1],
+  [-1, 1],
+  [-1, 0],
+  [-1, -1],
+  [0, -1],
+  [1, -1],
+];
+
+export function layoutAnnotationBadges(
+  anchors: readonly AnnotationBadgeAnchor[],
+  viewport: AnnotationBox,
+  preferredGap = ANNOTATION_BADGE_GAP_PX,
+): AnnotationBadgeAnchor[] {
+  const minLeft = viewport.left + ANNOTATION_REVIEW_MARGIN_PX;
+  const maxLeft = viewport.right - ANNOTATION_REVIEW_MARGIN_PX;
+  const minTop = viewport.top + 8;
+  const maxTop = viewport.bottom - ANNOTATION_REVIEW_MARGIN_PX;
+  const gap = annotationBadgePackGap(viewport, anchors.length, preferredGap);
+  const cells = annotationAxisStops(minLeft, maxLeft, gap).flatMap((left) =>
+    annotationAxisStops(minTop, maxTop, gap).map((top) => ({ left, top })),
+  );
+  const placed: AnnotationBadgeAnchor[] = [];
+  for (const anchor of [...anchors].sort((left, right) => left.ordinal - right.ordinal)) {
+    const originLeft = clampAnnotationAxis(anchor.left, minLeft, maxLeft);
+    const originTop = clampAnnotationAxis(anchor.top, minTop, maxTop);
+    const seen = new Set<string>();
+    const candidates: Array<{ left: number; top: number }> = [];
+    const pushCandidate = (left: number, top: number) => {
+      if (left < minLeft || left > maxLeft || top < minTop || top > maxTop) return;
+      const key = annotationPointKey(left, top);
+      if (seen.has(key)) return;
+      seen.add(key);
+      candidates.push({ left, top });
+    };
+    pushCandidate(originLeft, originTop);
+    for (const [dx, dy] of ANNOTATION_BADGE_SHIFT_DIRS) {
+      const colliders = [...placed].sort(
+        (left, right) => right.left * dx + right.top * dy - (left.left * dx + left.top * dy),
+      );
+      for (const collider of colliders) {
+        pushCandidate(collider.left + dx * gap, collider.top + dy * gap);
+      }
+    }
+    const maxRadius =
+      Math.ceil(Math.max(maxLeft - minLeft, maxTop - minTop) / Math.max(gap, 1)) + 1;
+    for (let radius = 1; radius <= maxRadius; radius++) {
+      const ring: Array<[number, number]> = [];
+      for (let dx = -radius; dx <= radius; dx++) {
+        for (let dy = -radius; dy <= radius; dy++) {
+          if (Math.max(Math.abs(dx), Math.abs(dy)) !== radius) continue;
+          ring.push([dx, dy]);
+        }
+      }
+      ring.sort((left, right) => {
+        const leftDir = (left[0] < 0 ? 2 : 0) + (left[1] < 0 ? 1 : 0);
+        const rightDir = (right[0] < 0 ? 2 : 0) + (right[1] < 0 ? 1 : 0);
+        if (leftDir !== rightDir) return leftDir - rightDir;
+        const hypot = Math.hypot(left[0], left[1]) - Math.hypot(right[0], right[1]);
+        if (hypot !== 0) return hypot;
+        if (left[0] !== right[0]) return right[0] - left[0];
+        return left[1] - right[1];
+      });
+      for (const [dx, dy] of ring) {
+        pushCandidate(originLeft + dx * gap, originTop + dy * gap);
+      }
+    }
+    for (const cell of cells) {
+      pushCandidate(cell.left, cell.top);
+    }
+    const free = candidates.find((point) =>
+      annotationPointFree(point.left, point.top, placed, gap),
+    );
+    let chosen = free ?? candidates[0]!;
+    if (!free && placed.length > 0) {
+      let bestMin = Number.NEGATIVE_INFINITY;
+      for (const point of candidates) {
+        const minDist = placed.reduce(
+          (current, other) =>
+            Math.min(current, Math.hypot(point.left - other.left, point.top - other.top)),
+          Number.POSITIVE_INFINITY,
+        );
+        if (minDist > bestMin) {
+          bestMin = minDist;
+          chosen = point;
+        }
+      }
+    }
+    placed.push({ ...anchor, left: chosen.left, top: chosen.top });
+  }
+  return placed;
+}
+
+export function scrollAnnotationRowIntoList(
+  list: HTMLElement | null | undefined,
+  row: HTMLElement | null | undefined,
+): void {
+  if (!list || !row || !list.contains(row)) return;
+  const listRect = list.getBoundingClientRect();
+  const rowRect = row.getBoundingClientRect();
+  if (rowRect.top < listRect.top) {
+    list.scrollTop -= listRect.top - rowRect.top;
+    return;
+  }
+  if (rowRect.bottom > listRect.bottom) {
+    list.scrollTop += rowRect.bottom - listRect.bottom;
+  }
+}
+
+export function clampAnnotationDialogPlacement(input: {
+  triggerLeft: number;
+  triggerTop: number;
+  triggerBottom: number;
+  contentHeight: number;
+  viewportWidth: number;
+  viewportHeight: number;
+  panelWidth?: number;
+}): {
+  left: number;
+  top: number;
+  maxHeight: number;
+  above: boolean;
+} {
+  const margin = ANNOTATION_REVIEW_MARGIN_PX;
+  const panelWidth = Math.min(
+    input.panelWidth ?? ANNOTATION_REVIEW_DIALOG_WIDTH_PX,
+    Math.max(1, input.viewportWidth - margin * 2),
+  );
+  const left = Math.min(
+    Math.max(margin, input.triggerLeft),
+    Math.max(margin, input.viewportWidth - panelWidth - margin),
+  );
+  const spaceBelow = input.viewportHeight - input.triggerBottom - margin;
+  const spaceAbove = input.triggerTop - margin;
+  const above = spaceBelow < Math.min(input.contentHeight, 200) && spaceAbove > spaceBelow;
+  const viewportBudget = Math.max(
+    ANNOTATION_REVIEW_DIALOG_FLOOR_HEIGHT_PX,
+    input.viewportHeight - margin * 2,
+  );
+  const available = Math.max(
+    Math.min(ANNOTATION_REVIEW_DIALOG_MIN_HEIGHT_PX, viewportBudget),
+    above ? spaceAbove : spaceBelow,
+  );
+  let maxHeight = Math.min(
+    Math.max(input.contentHeight, Math.min(ANNOTATION_REVIEW_DIALOG_MIN_HEIGHT_PX, viewportBudget)),
+    available,
+    Math.floor(input.viewportHeight * 0.7) || viewportBudget,
+    ANNOTATION_REVIEW_DIALOG_MAX_HEIGHT_PX,
+    viewportBudget,
+  );
+  let top = above
+    ? Math.max(margin, input.triggerTop - 8 - maxHeight)
+    : Math.min(
+        input.triggerBottom + 8,
+        Math.max(margin, input.viewportHeight - margin - maxHeight),
+      );
+  top = Math.max(margin, top);
+  maxHeight = Math.min(
+    maxHeight,
+    Math.max(ANNOTATION_REVIEW_DIALOG_FLOOR_HEIGHT_PX, input.viewportHeight - margin - top),
+  );
+  return { left, top, maxHeight, above };
+}