@hansenexus/hud 0.2.0 → 0.4.0

package/dist/review.d.ts

@@ -0,0 +1,181 @@
+import { t as HUD_REVIEW_MARKER } from "./marker-C66LxOhJ.js";
+//#region src/review/anchor/types.d.ts
+/** Which breakpoint band a pin was planted in. Cut on Tailwind's `md` and `xl`. */
+type ViewportBucket = "mobile" | "tablet" | "desktop";
+/** Box in viewport percentages. Kept only to draw the highlight on a stored screenshot. */
+interface PinRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+/**
+ * Everything stored when a pin is planted.
+ *
+ * The grabber's `buildGrabAnchor` stores a viewport-relative rect, which is correct for
+ * a grab that is dispatched in the same second and wrong for anything that
+ * persists: reload at a different scroll offset and the box has moved. A pin is
+ * therefore located by `selector` + `docX`/`docY` (fractions of the *document*,
+ * not the viewport), with the viewport rect kept only for the screenshot overlay.
+ */
+interface PinAnchor {
+  /** Lowercase tag name. Guards strategy 1 against matching a different node of the same shape. */
+  tag: string;
+  /** `nth-of-type` path from `document.body`. */
+  selector: string;
+  /** Unique, non-generated `#id` / `[data-testid=…]` selector, on the element or an ancestor. */
+  stableId?: string;
+  /** Path from the stable node down to the element. This is what makes strategy 2 more than a fallback. */
+  selectorFromStable?: string;
+  /** Human label, e.g. `button “Termin buchen”`. */
+  label: string;
+  /** Normalised leading text, for strategy 3. Absent when the element holds too much text to identify. */
+  textPrefix?: string;
+  /**
+   * Stable-ish identity for elements that carry no text — an icon button, an
+   * image, an input. Without it a text-less element can only ever be
+   * corroborated by its tag, which is far too weak.
+   */
+  signature?: string;
+  /** Where inside the element the reviewer clicked, 0..1. */
+  offsetX: number;
+  offsetY: number;
+  /** Position as a fraction of the full scrollable document — scroll-independent. */
+  docX: number;
+  docY: number;
+  rect: PinRect;
+  viewportWidth: number;
+  viewportHeight: number;
+  scrollY: number;
+  viewportBucket: ViewportBucket;
+}
+/**
+ * How a pin was located on this render.
+ *
+ * There is deliberately no "container" outcome. Falling back to a surviving
+ * ancestor was tried and removed: text matching already recovers the reshuffle
+ * case it was meant for, and in the only case left — the element is genuinely
+ * gone — putting the pin on its parent asserts that the comment still applies
+ * to something on screen. It does not. That pin belongs in "Ohne Position".
+ */
+type AnchorStrategy = "exact" | "stable" | "identity";
+interface AnchorResolution {
+  element: Element;
+  strategy: AnchorStrategy;
+}
+//#endregion
+//#region src/review/anchor/capture.d.ts
+interface CapturePoint {
+  clientX: number;
+  clientY: number;
+}
+/**
+ * Snapshot everything needed to find this element again on a later render, at a
+ * possibly different scroll offset, viewport and content revision.
+ */
+export declare function capturePinAnchor(el: Element, point?: CapturePoint): PinAnchor;
+//#endregion
+//#region src/review/anchor/resolve.d.ts
+/**
+ * Locate a stored anchor on the current document.
+ *
+ * Returns null rather than guessing. A null resolution is a first-class
+ * outcome, not an error: the pin is shown in the "Ohne Position" list with its
+ * screenshot, where it stays actionable — and a pin that stops resolving is
+ * itself a signal that the thing it complained about is gone.
+ */
+export declare function resolveAnchor(anchor: PinAnchor, doc?: Document): AnchorResolution | null;
+//#endregion
+//#region src/review/anchor/viewport.d.ts
+export declare function viewportBucket(width: number): ViewportBucket;
+//#endregion
+//#region src/review/backend.d.ts
+interface ReviewSession {
+  sessionToken: string;
+  projectSlug: string;
+  displayName: string;
+}
+interface Reviewer {
+  displayName: string;
+  role: string;
+}
+interface ReviewPin {
+  _id: string;
+  number: number;
+  body: string;
+  authorName: string;
+  lane: "client" | "internal";
+  status: string;
+  anchor: PinAnchor;
+  viewportBucket: ViewportBucket;
+}
+interface PlantPin {
+  sessionToken: string;
+  route: string;
+  rawPath: string;
+  locale: string;
+  body: string;
+  anchor: PinAnchor;
+}
+/**
+ * What the widget needs from the review deployment. `convexReview()` is the
+ * one implementation; the seam exists so tests and the playground can run the
+ * widget without a Convex backend.
+ *
+ * `watch*` deliver the current value and every later change until the
+ * returned function is called. `null` from `watchReviewer` means the token is
+ * not (or no longer) valid.
+ */
+interface ReviewBackend {
+  redeemGrant: (grant: string) => Promise<ReviewSession>;
+  watchReviewer: (sessionToken: string, onChange: (reviewer: Reviewer | null) => void) => () => void;
+  watchPins: (sessionToken: string, route: string, onChange: (pins: ReviewPin[]) => void) => () => void;
+  plant: (pin: PlantPin) => Promise<unknown>;
+  /** Releases the connection when the widget unmounts. */
+  close?: () => void;
+}
+/** The review app's Convex deployment at `url`. */
+export declare function convexReview(url: string): ReviewBackend;
+//#endregion
+//#region src/review/review.d.ts
+interface ReviewProps {
+  /**
+   * Convex deployment of the review app. Empty or absent renders nothing, so
+   * the mounting app can switch the widget off per deployment at runtime.
+   */
+  convexUrl?: string | undefined;
+  /** Project slug this surface belongs to. */
+  projectSlug: string;
+  /** Active locale, used to derive the locale-stripped route key. */
+  locale: string;
+  /** Replaces the Convex backend, for tests and the playground. Keep it stable. */
+  backend?: ReviewBackend | undefined;
+}
+/**
+ * The production-safe review widget: a pill, the element picker and a docked
+ * review sheet with the page's pins.
+ *
+ * Everything arrives as a prop and nothing is read from `process.env`. That is
+ * what makes the runtime gate work: an app that ships one image to two
+ * productions has identical build-time flags on both, so a build flag could not
+ * switch the widget off where it must be off. The mounting app decides, per
+ * deployment, by passing `convexUrl` or not.
+ *
+ * Nothing renders, and no DOM is touched, until a reviewer session exists:
+ * a visitor without a review link never sees a pill.
+ */
+export declare function Review({ convexUrl, projectSlug, locale, backend }: ReviewProps): import("react").JSX.Element | null;
+//#endregion
+//#region src/review/route.d.ts
+/**
+ * The route a pin belongs to.
+ *
+ * Locale-stripped on purpose: with `localePrefix: "as-needed"` the German page
+ * is `/standorte/wedel` and the English one `/en/standorte/wedel`. Storing the
+ * raw path would make those two different routes, so a pin left by a German
+ * reviewer would be invisible to anyone reading the English page — and the same
+ * layout bug would be reported once per language.
+ */
+export declare function routeKey(pathname: string, locale: string): string;
+//#endregion
+export { type AnchorStrategy, HUD_REVIEW_MARKER, type PinAnchor, type PlantPin, type ReviewBackend, type ReviewPin, type ReviewProps, type ReviewSession, type Reviewer, type ViewportBucket };