@epam/ai-dial-quotations 1.1.0-dev.88

package/components/CitationCard/CitationCard.d.ts

@@ -0,0 +1,59 @@
+import { Annotation } from '@epam/ai-dial-chat-shared';
+import { FC, ReactNode } from 'react';
+import { AnnotationGroup } from '../../utils/group-annotations-by-source';
+/** User-visible strings for `CitationCard`. */
+export interface CitationCardLabels {
+    /** Dialog aria-label (already includes the source name). */
+    ariaLabel: string;
+    /** Accessible label for the "previous citation" button. */
+    previousCitation: string;
+    /** Accessible label for the "next citation" button. */
+    nextCitation: string;
+    /** Returns the switcher text given the 1-based current index and total count, e.g. `(1, 3) => "1 / 3"`. */
+    formatSwitcherText: (current: number, total: number) => string;
+    /** Label for the "Preview" button. */
+    preview: string;
+    /** Label for the "Open in browser" button. */
+    openInBrowser: string;
+    /** Label for the "Download" button. */
+    download: string;
+}
+/** Typography (font utility class) overrides for `CitationCard`. */
+export interface CitationCardTypography {
+    /** CSS class applied to the source name ellipsis. Defaults to `'dial-tiny-text'`. */
+    sourceNameClassName?: string;
+    /** CSS class applied to the annotation title. Defaults to `'dial-body-semi-text'`. */
+    titleClassName?: string;
+    /** CSS class applied to the quoted excerpt. Defaults to `'dial-small-text'`. */
+    quoteClassName?: string;
+    /** CSS class applied to the pagination switcher text. Defaults to `'dial-tiny-text'`. */
+    switcherClassName?: string;
+}
+/** Props for the `CitationCard` component. */
+export interface CitationCardProps {
+    /** The annotation group whose citations are displayed in this popup. */
+    group: AnnotationGroup;
+    /** Zero-based index into `group.annotations` for the currently shown citation. */
+    activeIndex: number;
+    /** Called when the user navigates to a different annotation within the group. */
+    onIndexChange: (index: number) => void;
+    /**
+     * Called when the user clicks the "Preview" button. Omit when the group has
+     * nothing previewable (e.g. reference-only chunks) — the "Preview" button is
+     * hidden and the remaining button is always labelled "Open in browser".
+     */
+    onPreview?: (annotation: Annotation) => void;
+    /** Called when the user clicks the "Open in browser"/"Download" button. */
+    onOpenInBrowser: (annotation: Annotation) => void;
+    /** Optional icon rendered before the source name in the card header. */
+    headerIcon?: ReactNode;
+    /** User-visible strings. */
+    labels: CitationCardLabels;
+    /** Optional typography class overrides. */
+    typography?: CitationCardTypography;
+}
+/** Popup card displaying a citation's title, quoted excerpt, and navigation controls. */
+export declare const CitationCard: FC<CitationCardProps>;
+declare const _default: import('react').NamedExoticComponent<CitationCardProps>;
+export default _default;
+//# sourceMappingURL=CitationCard.d.ts.map

package/components/CitationCard/CitationCard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CitationCard.d.ts","sourceRoot":"","sources":["../../../src/components/CitationCard/CitationCard.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAa5D,OAAO,EAAE,EAAE,EAAQ,SAAS,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAE/E,+CAA+C;AAC/C,MAAM,WAAW,kBAAkB;IACjC,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,gBAAgB,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB,2GAA2G;IAC3G,kBAAkB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAC/D,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,aAAa,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,oEAAoE;AACpE,MAAM,WAAW,sBAAsB;IACrC,qFAAqF;IACrF,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,sFAAsF;IACtF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gFAAgF;IAChF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yFAAyF;IACzF,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,KAAK,EAAE,eAAe,CAAC;IACvB,kFAAkF;IAClF,WAAW,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,IAAI,CAAC;IAC7C,2EAA2E;IAC3E,eAAe,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,IAAI,CAAC;IAClD,wEAAwE;IACxE,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB,4BAA4B;IAC5B,MAAM,EAAE,kBAAkB,CAAC;IAC3B,2CAA2C;IAC3C,UAAU,CAAC,EAAE,sBAAsB,CAAC;CACrC;AAED,yFAAyF;AACzF,eAAO,MAAM,YAAY,EAAE,EAAE,CAAC,iBAAiB,CAmH9C,CAAC;;AAEF,wBAAkC"}

package/components/CitationDropdown/CitationDropdown.d.ts

@@ -0,0 +1,32 @@
+import { Annotation } from '@epam/ai-dial-chat-shared';
+import { FC, ReactNode } from 'react';
+import { AnnotationGroup } from '../../utils/group-annotations-by-source';
+import { CitationCardLabels, CitationCardTypography } from '../CitationCard/CitationCard';
+import { CitationMarkerLabels } from '../CitationMarker/CitationMarker';
+/** Props for the `CitationDropdown` component. */
+export interface CitationDropdownProps {
+    /** The annotation group represented by this marker+popup pair. */
+    group: AnnotationGroup;
+    /**
+     * Called when the user clicks "Preview" for an annotation. Omit when the
+     * group has nothing previewable — the "Preview" button is hidden.
+     */
+    onPreview?: (annotation: Annotation) => void;
+    /** Called when the user clicks "Open in browser" for an annotation. */
+    onOpenInBrowser: (annotation: Annotation) => void;
+    /** Optional icon rendered before the marker's label. */
+    icon?: ReactNode;
+    /** Optional icon rendered in the card header. When absent, no header icon is shown. */
+    headerIcon?: ReactNode;
+    /** User-visible strings for the card popup. */
+    cardLabels: CitationCardLabels;
+    /** User-visible strings for the inline marker button. */
+    markerLabels: CitationMarkerLabels;
+    /** Optional typography overrides forwarded to the card. */
+    cardTypography?: CitationCardTypography;
+}
+/** Combines `CitationMarker` and `CitationCard` into a tooltip-based dropdown. Requires a `CitationCardProvider` ancestor. */
+export declare const CitationDropdown: FC<CitationDropdownProps>;
+declare const _default: import('react').NamedExoticComponent<CitationDropdownProps>;
+export default _default;
+//# sourceMappingURL=CitationDropdown.d.ts.map

package/components/CitationDropdown/CitationDropdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CitationDropdown.d.ts","sourceRoot":"","sources":["../../../src/components/CitationDropdown/CitationDropdown.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D,OAAO,EAAE,EAAE,EAAQ,SAAS,EAAwB,MAAM,OAAO,CAAC;AAElE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAC/E,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC5B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,kCAAkC,CAAC;AAE1C,kDAAkD;AAClD,MAAM,WAAW,qBAAqB;IACpC,kEAAkE;IAClE,KAAK,EAAE,eAAe,CAAC;IACvB;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,IAAI,CAAC;IAC7C,uEAAuE;IACvE,eAAe,EAAE,CAAC,UAAU,EAAE,UAAU,KAAK,IAAI,CAAC;IAClD,wDAAwD;IACxD,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,uFAAuF;IACvF,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB,+CAA+C;IAC/C,UAAU,EAAE,kBAAkB,CAAC;IAC/B,yDAAyD;IACzD,YAAY,EAAE,oBAAoB,CAAC;IACnC,2DAA2D;IAC3D,cAAc,CAAC,EAAE,sBAAsB,CAAC;CACzC;AAED,8HAA8H;AAC9H,eAAO,MAAM,gBAAgB,EAAE,EAAE,CAAC,qBAAqB,CA6DtD,CAAC;;AAEF,wBAAsC"}

package/components/CitationMarker/CitationMarker.d.ts

@@ -0,0 +1,28 @@
+import { FC, ReactNode } from 'react';
+/** User-visible strings for `CitationMarker`. */
+export interface CitationMarkerLabels {
+    /** Accessible label for the marker button. */
+    ariaLabel: string;
+    /** Button text when `annotationCount === 1`. */
+    label: string;
+    /** Button text when `annotationCount > 1`. */
+    labelWithOverflow: string;
+}
+/** Props for the `CitationMarker` component. */
+export interface CitationMarkerProps {
+    /** Human-readable source name derived from the attachment URL. */
+    sourceName: string;
+    /** Total number of annotations in this citation group. */
+    annotationCount: number;
+    /** Called when the user clicks the marker to open the citation popup. */
+    onOpen: () => void;
+    /** Optional icon rendered before the label; omitted by default. */
+    icon?: ReactNode;
+    /** User-visible strings. */
+    labels: CitationMarkerLabels;
+}
+/** Inline button that opens the citation popup for a source group. */
+export declare const CitationMarker: FC<CitationMarkerProps>;
+declare const _default: import('react').NamedExoticComponent<CitationMarkerProps>;
+export default _default;
+//# sourceMappingURL=CitationMarker.d.ts.map

package/components/CitationMarker/CitationMarker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CitationMarker.d.ts","sourceRoot":"","sources":["../../../src/components/CitationMarker/CitationMarker.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,EAAE,EAAQ,SAAS,EAAE,MAAM,OAAO,CAAC;AAE5C,iDAAiD;AACjD,MAAM,WAAW,oBAAoB;IACnC,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,gDAAgD;AAChD,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,eAAe,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,mEAAmE;IACnE,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,4BAA4B;IAC5B,MAAM,EAAE,oBAAoB,CAAC;CAC9B;AAED,sEAAsE;AACtE,eAAO,MAAM,cAAc,EAAE,EAAE,CAAC,mBAAmB,CAuBlD,CAAC;;AAEF,wBAAoC"}

package/context/CitationCardContext.d.ts

@@ -0,0 +1,14 @@
+import { useCitationCard } from '../utils/useCitationCard';
+/** The shape returned by `useCitationCard`. */
+export type CitationCardHook = ReturnType<typeof useCitationCard>;
+/** Provider that supplies `CitationCardHook` state to a citation subtree. */
+export declare const CitationCardProvider: import('react').Provider<{
+    openPopup: (sourceUrl: string) => void;
+    closePopup: () => void;
+    setActiveIndex: (sourceUrl: string, index: number) => void;
+    isOpen: (sourceUrl: string) => boolean;
+    getActiveIndex: (sourceUrl: string) => number;
+} | null>;
+/** Returns the nearest `CitationCardHook` from context. Throws when used outside a `CitationCardProvider`. */
+export declare const useCitationCardContext: () => CitationCardHook;
+//# sourceMappingURL=CitationCardContext.d.ts.map

package/context/CitationCardContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CitationCardContext.d.ts","sourceRoot":"","sources":["../../src/context/CitationCardContext.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhE,+CAA+C;AAC/C,MAAM,MAAM,gBAAgB,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;AAIlE,6EAA6E;AAC7E,eAAO,MAAM,oBAAoB;;;;;;SAA+B,CAAC;AAEjE,8GAA8G;AAC9G,eAAO,MAAM,sBAAsB,QAAO,gBAOzC,CAAC"}

package/index.d.ts

@@ -0,0 +1,18 @@
+export { CitationCard } from './components/CitationCard/CitationCard';
+export type { CitationCardLabels, CitationCardProps, CitationCardTypography, } from './components/CitationCard/CitationCard';
+export { CitationMarker } from './components/CitationMarker/CitationMarker';
+export type { CitationMarkerLabels, CitationMarkerProps, } from './components/CitationMarker/CitationMarker';
+export { CitationDropdown } from './components/CitationDropdown/CitationDropdown';
+export type { CitationDropdownProps } from './components/CitationDropdown/CitationDropdown';
+export { CitationCardProvider, useCitationCardContext, } from './context/CitationCardContext';
+export type { CitationCardHook } from './context/CitationCardContext';
+export { useAnnotations } from './utils/useAnnotations';
+export { useCitationCard } from './utils/useCitationCard';
+export { groupAnnotationsBySource } from './utils/group-annotations-by-source';
+export type { AnnotationGroup } from './utils/group-annotations-by-source';
+export { annotationsToPdfHighlights, annotationHighlightId, normalizeRawAnnotations, resolveMessageAnnotations, } from './utils/annotation';
+export type { AttachmentResource } from './utils/annotation';
+export { injectCitationSentinels, replaceSentinelsInChildren, } from './utils/citation-injection';
+export { isReferenceOnlyAttachment, parsePdfPageReference, getReferenceAttachmentGroups, } from './utils/reference-attachment';
+export type { PdfPageReference } from './utils/reference-attachment';
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,wCAAwC,CAAC;AACtE,YAAY,EACV,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,wCAAwC,CAAC;AAEhD,OAAO,EAAE,cAAc,EAAE,MAAM,4CAA4C,CAAC;AAC5E,YAAY,EACV,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,4CAA4C,CAAC;AAEpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gDAAgD,CAAC;AAClF,YAAY,EAAE,qBAAqB,EAAE,MAAM,gDAAgD,CAAC;AAG5F,OAAO,EACL,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,+BAA+B,CAAC;AACvC,YAAY,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGtE,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG1D,OAAO,EAAE,wBAAwB,EAAE,MAAM,qCAAqC,CAAC;AAC/E,YAAY,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AAE3E,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,EACrB,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE7D,OAAO,EACL,uBAAuB,EACvB,0BAA0B,GAC3B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EACL,yBAAyB,EACzB,qBAAqB,EACrB,4BAA4B,GAC7B,MAAM,8BAA8B,CAAC;AACtC,YAAY,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC"}

package/index.js

@@ -0,0 +1,320 @@
+import { MIMEType as e, MarkdownRenderer as t, mergeClasses as n } from "@epam/ai-dial-chat-shared";
+import { DialEllipsisTooltip as r, DialTooltip as i, ElementSize as a, GhostIconButton as o, NeutralButton as s, PrimaryButton as c } from "@epam/ai-dial-ui-kit";
+import { IconChevronLeft as l, IconChevronRight as u } from "@tabler/icons-react";
+import { createContext as d, memo as f, useCallback as p, useContext as m, useMemo as h, useState as g } from "react";
+import { jsx as _, jsxs as v } from "react/jsx-runtime";
+//#region src/components/CitationCard/CitationCard.tsx
+var y = ({ group: i, activeIndex: s, onIndexChange: d, onPreview: f, onOpenInBrowser: p, headerIcon: m, labels: h, typography: g }) => {
+	let y = i.annotations.length, b = i.annotations[s] ?? i.primaryAnnotation, x = y > 1, S = i.annotations.some((e) => e.body?.title), C = i.primaryAnnotation.body?.source?.attachment?.type, w = f == null || C === e.HTML || C === e.XHTML, T = g?.sourceNameClassName ?? "dial-tiny-text", E = g?.titleClassName ?? "dial-body-semi-text", D = g?.quoteClassName ?? "dial-small-text", O = g?.switcherClassName ?? "dial-tiny-text";
+	return /* @__PURE__ */ v("div", {
+		role: "dialog",
+		"aria-modal": "true",
+		"aria-label": h.ariaLabel,
+		className: "flex w-[400px] flex-col gap-3 rounded-lg border border-primary bg-layer-0 p-4 shadow-lg",
+		children: [
+			/* @__PURE__ */ v("div", {
+				className: "flex items-center justify-between gap-2",
+				children: [/* @__PURE__ */ v("div", {
+					className: "flex min-w-0 items-center gap-1",
+					children: [m, /* @__PURE__ */ _(r, {
+						text: i.sourceName,
+						className: n(T, "min-w-0 text-primary")
+					})]
+				}), x && /* @__PURE__ */ v("div", {
+					className: "flex shrink-0 items-center gap-1",
+					children: [
+						/* @__PURE__ */ _(o, {
+							icon: /* @__PURE__ */ _(l, {
+								size: 14,
+								className: "rtl:scale-x-[-1]"
+							}),
+							size: a.Small,
+							"aria-label": h.previousCitation,
+							onClick: () => d((s - 1 + y) % y)
+						}),
+						/* @__PURE__ */ _("span", {
+							className: n(O, "text-secondary"),
+							children: h.formatSwitcherText(s + 1, y)
+						}),
+						/* @__PURE__ */ _(o, {
+							icon: /* @__PURE__ */ _(u, {
+								size: 14,
+								className: "rtl:scale-x-[-1]"
+							}),
+							size: a.Small,
+							"aria-label": h.nextCitation,
+							onClick: () => d((s + 1) % y)
+						})
+					]
+				})]
+			}),
+			(b.body?.title || b.body?.quote || x) && /* @__PURE__ */ v("div", {
+				className: "flex flex-col gap-3",
+				children: [(b.body?.title || x && S) && /* @__PURE__ */ _("p", {
+					className: n(E, "text-primary", x && S && "min-h-[1lh]"),
+					children: b.body?.title
+				}), (b.body?.quote || x) && /* @__PURE__ */ _("div", {
+					className: n(x && "min-h-[3lh]"),
+					children: b.body?.quote && /* @__PURE__ */ _(t, {
+						content: b.body.quote,
+						classNames: { p: n(D, "line-clamp-6 text-secondary") }
+					})
+				})]
+			}),
+			/* @__PURE__ */ v("div", {
+				className: "flex justify-start gap-2",
+				children: [f && /* @__PURE__ */ _(c, {
+					label: h.preview,
+					size: a.Small,
+					onClick: () => f(b)
+				}), /* @__PURE__ */ _(c, {
+					label: w ? h.openInBrowser : h.download,
+					size: a.Small,
+					onClick: () => p(b)
+				})]
+			})
+		]
+	});
+};
+f(y);
+//#endregion
+//#region src/components/CitationMarker/CitationMarker.tsx
+var b = ({ annotationCount: e, onOpen: t, icon: n, labels: r }) => {
+	let i = /* @__PURE__ */ v("span", {
+		className: "flex items-center gap-1",
+		children: [n, /* @__PURE__ */ _("span", {
+			className: "dial-caption-text",
+			children: e > 1 ? r.labelWithOverflow : r.label
+		})]
+	});
+	return /* @__PURE__ */ _(s, {
+		size: a.Small,
+		label: i,
+		"aria-label": r.ariaLabel,
+		onClick: t
+	});
+};
+f(b);
+//#endregion
+//#region src/context/CitationCardContext.tsx
+var x = d(null), S = x.Provider, C = () => {
+	let e = m(x);
+	if (e == null) throw Error("useCitationCardContext must be used within a CitationCardProvider");
+	return e;
+}, w = ({ group: e, onPreview: t, onOpenInBrowser: n, icon: r, headerIcon: a, cardLabels: o, markerLabels: s, cardTypography: c }) => {
+	let l = C(), u = l.isOpen(e.sourceUrl), d = l.getActiveIndex(e.sourceUrl);
+	return /* @__PURE__ */ _(i, {
+		open: u,
+		onOpenChange: p((e) => {
+			e || l.closePopup();
+		}, [l]),
+		placement: "bottom-end",
+		triggerClassName: "ms-1 inline-flex align-middle",
+		contentClassName: "!p-0 !bg-transparent !border-0 !shadow-none !max-w-none !rounded-none",
+		tooltip: /* @__PURE__ */ _(y, {
+			group: e,
+			activeIndex: d,
+			onIndexChange: (t) => l.setActiveIndex(e.sourceUrl, t),
+			onPreview: h(() => t ? (e) => {
+				t(e), l.closePopup();
+			} : void 0, [t, l]),
+			onOpenInBrowser: n,
+			headerIcon: a,
+			labels: o,
+			typography: c
+		}),
+		children: /* @__PURE__ */ _(b, {
+			sourceName: e.sourceName,
+			annotationCount: e.annotations.length,
+			onOpen: () => l.openPopup(e.sourceUrl),
+			icon: r,
+			labels: s
+		})
+	});
+};
+f(w);
+//#endregion
+//#region src/utils/annotation.ts
+var T = {
+	backgroundColor: "transparent",
+	borderColor: "#124ACE",
+	borderWidth: "2px",
+	opacity: .5,
+	hoverOpacity: .5
+}, E = (e) => e.flatMap((e, t) => {
+	let n = e.body?.selector;
+	if (n == null) return [];
+	let r = (Array.isArray(n) ? n : [n]).flatMap((e) => {
+		if (e.type !== "pdf_bbox") return [];
+		let { page: t, x1: n, y1: r, x2: i, y2: a } = e;
+		return [{
+			page: t,
+			x1: n,
+			y1: r,
+			x2: i,
+			y2: a
+		}];
+	});
+	return r.length === 0 ? [] : [{
+		id: String(e.index ?? t),
+		bboxes: r,
+		style: T
+	}];
+}), D = (e, t) => String(e.index ?? t), O = (e) => typeof e == "number" ? e : null, k = (e) => {
+	if (typeof e != "object" || !e) return null;
+	let t = e;
+	if (t.type !== "pdf_region") return null;
+	let n = t.bbox;
+	if (typeof n != "object" || !n) return null;
+	let r = n, i = O(r.left), a = O(r.top), o = O(r.width), s = O(r.height);
+	return i === null || a === null || o === null || s === null ? null : {
+		type: "pdf_bbox",
+		page: O(t.page) ?? 1,
+		x1: i,
+		y1: a,
+		x2: i + o,
+		y2: a + s
+	};
+}, A = (t, n) => t.flatMap((t) => {
+	if (typeof t != "object" || !t) return [];
+	let r = t, i = r.target;
+	if (typeof i != "object" || !i) return [];
+	let a = i, o = a.source;
+	if (typeof o != "object" || !o) return [];
+	let s = O(o.attachment_index);
+	if (s === null) return [];
+	let c = n.find((e) => e.index === s);
+	if (c?.url == null) return [];
+	let l = k(a.selector);
+	if (l === null) return [];
+	let u = r.body, d = typeof u == "object" && u ? u : {}, f = typeof d.title == "string" ? d.title : void 0, p = typeof d.quote == "string" ? d.quote : void 0;
+	return [{
+		index: O(r.index) ?? void 0,
+		body: {
+			title: f,
+			quote: p,
+			source: {
+				type: "attachment",
+				attachment: {
+					type: c.type ?? e.PDF,
+					url: c.url,
+					title: c.title
+				}
+			},
+			selector: l
+		}
+	}];
+}), j = (e) => {
+	let t = e.custom_content?.annotations;
+	if (t?.length) return t.filter((e) => e != null && e.body?.source?.attachment?.url != null);
+	let n = e.custom_fields;
+	if (typeof n != "object" || !n) return [];
+	let r = n.annotations;
+	return !Array.isArray(r) || r.length === 0 ? [] : A(r, e.custom_content?.attachments ?? []);
+}, M = (e, t) => h(() => t ? [] : j(e), [t, e]), N = {
+	openGroupSourceUrl: null,
+	activeIndexByGroup: {}
+}, P = () => {
+	let [e, t] = g(N), n = p((e) => {
+		t((t) => ({
+			...t,
+			openGroupSourceUrl: e
+		}));
+	}, []), r = p(() => {
+		t((e) => ({
+			...e,
+			openGroupSourceUrl: null
+		}));
+	}, []), i = p((e, n) => {
+		t((t) => ({
+			...t,
+			activeIndexByGroup: {
+				...t.activeIndexByGroup,
+				[e]: n
+			}
+		}));
+	}, []);
+	return h(() => ({
+		openPopup: n,
+		closePopup: r,
+		setActiveIndex: i,
+		isOpen: (t) => e.openGroupSourceUrl === t,
+		getActiveIndex: (t) => e.activeIndexByGroup[t] ?? 0
+	}), [
+		n,
+		r,
+		i,
+		e
+	]);
+}, F = (e) => {
+	try {
+		return decodeURIComponent(e);
+	} catch {
+		return e;
+	}
+}, I = (e) => {
+	try {
+		let t = new URL(e);
+		return t.pathname.split("/").map((e) => F(e)).filter(Boolean).at(-1) ?? t.hostname;
+	} catch {
+		return e.split("/").map((e) => F(e)).filter(Boolean).at(-1) ?? e;
+	}
+}, L = (e) => {
+	let t = /* @__PURE__ */ new Map();
+	for (let n of e) {
+		let e = n.body?.source?.attachment?.url;
+		if (e == null) continue;
+		let r = t.get(e);
+		r ? r.annotations.push(n) : t.set(e, {
+			sourceUrl: e,
+			sourceName: n.body?.source?.attachment?.title ?? I(e),
+			annotations: [n],
+			primaryAnnotation: n
+		});
+	}
+	return Array.from(t.values());
+}, R = /⟦C(\d+)⟧/g, z = (e, t) => {
+	let n = t.map((t, n) => {
+		let r = t.primaryAnnotation.target?.selector, i = typeof r == "object" && r && "type" in r && r.type === "text_character_range" ? r.end : e.length;
+		return {
+			idx: n,
+			pos: Math.min(i, e.length)
+		};
+	}).sort((e, t) => t.pos - e.pos), r = e;
+	for (let { idx: e, pos: t } of n) r = `${r.slice(0, t)}⟦C${e}⟧${r.slice(t)}`;
+	return r;
+}, B = (e, t) => {
+	if (typeof e == "string") {
+		let n = e.split(R);
+		if (n.length === 1) return e;
+		let r = [];
+		return n.forEach((e, n) => {
+			n % 2 == 1 ? r.push(t(parseInt(e, 10))) : e && r.push(e);
+		}), r;
+	}
+	return Array.isArray(e) ? e.flatMap((e) => {
+		let n = B(e, t);
+		return Array.isArray(n) ? n : [n];
+	}) : e;
+}, V = (e) => e.url == null && e.reference_url != null, H = /^(.*\.pdf)(?:#page=(\d+))?$/i, U = (e) => {
+	let t = H.exec(e);
+	return t ? {
+		baseUrl: t[1],
+		page: t[2] == null ? null : Number(t[2])
+	} : null;
+}, W = (t) => L((t ?? []).filter(V).map((t) => {
+	let n = t.reference_url, r = U(n) != null;
+	return { body: {
+		quote: t.data,
+		source: {
+			type: "attachment",
+			attachment: {
+				type: r ? e.PDF : t.reference_type ?? t.type ?? "",
+				url: n,
+				title: t.title
+			}
+		}
+	} };
+}));
+//#endregion
+export { y as CitationCard, S as CitationCardProvider, w as CitationDropdown, b as CitationMarker, D as annotationHighlightId, E as annotationsToPdfHighlights, W as getReferenceAttachmentGroups, L as groupAnnotationsBySource, z as injectCitationSentinels, V as isReferenceOnlyAttachment, A as normalizeRawAnnotations, U as parsePdfPageReference, B as replaceSentinelsInChildren, j as resolveMessageAnnotations, M as useAnnotations, P as useCitationCard, C as useCitationCardContext };

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@epam/ai-dial-quotations",
+  "description": "Citation and annotation components, hooks, and utilities for AI DIAL conversations",
+  "version": "1.1.0-dev.88",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./index.js",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "@tabler/icons-react": "^3.0.0",
+    "@epam/ai-dial-chat-shared": "1.1.0-dev.88",
+    "@epam/ai-dial-ui-kit": "^0.13.0-dev.26",
+    "@epam/pdf-highlighter-kit": ">=0.0.14"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/epam/ai-dial-chat.git",
+    "directory": "libs/quotations"
+  }
+}

package/test-setup.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=test-setup.d.ts.map

package/test-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-setup.d.ts","sourceRoot":"","sources":["../src/test-setup.ts"],"names":[],"mappings":""}

package/utils/annotation.d.ts

@@ -0,0 +1,34 @@
+import { Annotation, AttachmentResource, Message, MessageAttachment } from '@epam/ai-dial-chat-shared';
+import { InputHighlightData } from '@epam/pdf-highlighter-kit';
+/**
+ * Maps a list of annotations to `InputHighlightData` entries for the PDF viewer.
+ * Annotations whose `body.selector` contains no `pdf_bbox` selectors are skipped.
+ * The highlight `id` is `annotation.index` when present, otherwise the position
+ * in the input array.
+ */
+export declare const annotationsToPdfHighlights: (annotations: Annotation[]) => InputHighlightData[];
+/** Returns a stable string ID for a given annotation, matching the IDs produced by `annotationsToPdfHighlights`. */
+export declare const annotationHighlightId: (annotation: Annotation, fallbackIndex: number) => string;
+/**
+ * Normalizes raw annotations from the API wire format (stored in
+ * `message.custom_fields.annotations`) to the internal `Annotation` model.
+ *
+ * The API format uses `target.source.attachment_index` (integer) and a
+ * `pdf_region` selector with `{ left, top, width, height }` coordinates.
+ * The internal model uses `body.source.attachment.url` (resolved URL) and a
+ * `pdf_bbox` selector with `{ x1, y1, x2, y2 }` coordinates.
+ *
+ * Annotations whose attachment index cannot be resolved or whose selector
+ * is not a recognised PDF region are omitted from the result.
+ */
+export declare const normalizeRawAnnotations: (rawAnnotations: unknown[], attachments: MessageAttachment[]) => Annotation[];
+/**
+ * Resolves the annotation list for a message regardless of how it was loaded.
+ *
+ * Prefers `custom_content.annotations` (internal format) when present.
+ * Falls back to `custom_fields.annotations` (raw API wire format) and
+ * normalises those entries using the message's `custom_content.attachments`.
+ */
+export declare const resolveMessageAnnotations: (message: Message) => Annotation[];
+export type { AttachmentResource };
+//# sourceMappingURL=annotation.d.ts.map

package/utils/annotation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotation.d.ts","sourceRoot":"","sources":["../../src/utils/annotation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,kBAAkB,EAClB,OAAO,EACP,iBAAiB,EAElB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAEV,kBAAkB,EACnB,MAAM,2BAA2B,CAAC;AAUnC;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,GACrC,aAAa,UAAU,EAAE,KACxB,kBAAkB,EAoBjB,CAAC;AAEL,oHAAoH;AACpH,eAAO,MAAM,qBAAqB,GAChC,YAAY,UAAU,EACtB,eAAe,MAAM,KACpB,MAAmD,CAAC;AA+BvD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,GAClC,gBAAgB,OAAO,EAAE,EACzB,aAAa,iBAAiB,EAAE,KAC/B,UAAU,EAmDT,CAAC;AAEL;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,OAAO,KAAG,UAAU,EAkBtE,CAAC;AAGF,YAAY,EAAE,kBAAkB,EAAE,CAAC"}

package/utils/citation-injection.d.ts

@@ -0,0 +1,15 @@
+import { ReactNode } from 'react';
+import { AnnotationGroup } from './group-annotations-by-source';
+/**
+ * Inserts sentinel strings into `content` at the `end` character offsets of
+ * each annotation group's primary selector. Offsets are processed in
+ * descending order so earlier insertions do not shift later ones.
+ */
+export declare const injectCitationSentinels: (content: string, groups: AnnotationGroup[]) => string;
+/**
+ * Recursively walks a React child tree and replaces sentinel strings with
+ * the result of `renderMarker(idx)`. Handles string children, arrays, and
+ * React elements whose `children` prop is a string.
+ */
+export declare const replaceSentinelsInChildren: (children: ReactNode, renderMarker: (idx: number) => ReactNode) => ReactNode;
+//# sourceMappingURL=citation-injection.d.ts.map

package/utils/citation-injection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citation-injection.d.ts","sourceRoot":"","sources":["../../src/utils/citation-injection.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAUrE;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,GAClC,SAAS,MAAM,EACf,QAAQ,eAAe,EAAE,KACxB,MAoBF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,GACrC,UAAU,SAAS,EACnB,cAAc,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,KACvC,SA0BF,CAAC"}

package/utils/group-annotations-by-source.d.ts

@@ -0,0 +1,18 @@
+import { Annotation } from '@epam/ai-dial-chat-shared';
+/** A set of annotations that all cite the same source document. */
+export interface AnnotationGroup {
+    /** The attachment URL shared by all annotations in this group. */
+    sourceUrl: string;
+    /**
+     * Human-readable name derived from the URL: the last non-empty path segment
+     * (decoded, without query params) when available, otherwise the URL hostname.
+     */
+    sourceName: string;
+    /** Every annotation in this group, in their original order. */
+    annotations: Annotation[];
+    /** The first annotation in the group — used for the inline citation marker position. */
+    primaryAnnotation: Annotation;
+}
+/** Groups annotations by their source attachment URL. Annotations without a `body.source.attachment.url` are excluded. */
+export declare const groupAnnotationsBySource: (annotations: Annotation[]) => AnnotationGroup[];
+//# sourceMappingURL=group-annotations-by-source.d.ts.map

package/utils/group-annotations-by-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-annotations-by-source.d.ts","sourceRoot":"","sources":["../../src/utils/group-annotations-by-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAE5D,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,wFAAwF;IACxF,iBAAiB,EAAE,UAAU,CAAC;CAC/B;AA2BD,0HAA0H;AAC1H,eAAO,MAAM,wBAAwB,GACnC,aAAa,UAAU,EAAE,KACxB,eAAe,EAsBjB,CAAC"}

package/utils/reference-attachment.d.ts

@@ -0,0 +1,24 @@
+import { MessageAttachment } from '@epam/ai-dial-chat-shared';
+import { AnnotationGroup } from './group-annotations-by-source';
+/**
+ * A `MessageAttachment` is "reference-only" when it carries a `reference_url`
+ * (e.g. a RAG/search-grounding chunk) but no directly downloadable `url`.
+ */
+export declare const isReferenceOnlyAttachment: (dto: MessageAttachment) => boolean;
+/** A reference URL pointing at a specific (optional) page of a PDF file. */
+export interface PdfPageReference {
+    /** The PDF file URL/id with the `#page=` fragment stripped. */
+    baseUrl: string;
+    /** 1-based page number, or `null` when the reference has no page fragment. */
+    page: number | null;
+}
+/** Parses a reference URL that points at a PDF file, optionally with a `#page=N` fragment. Returns `null` when the URL does not target a PDF. */
+export declare const parsePdfPageReference: (url: string) => PdfPageReference | null;
+/**
+ * Maps reference-only attachments to synthetic {@link Annotation}s and groups
+ * them by `reference_url`, reusing the same grouping core inline citations use,
+ * so repeated chunks from the same source collapse into one group with a
+ * Prev/Next switcher.
+ */
+export declare const getReferenceAttachmentGroups: (dtos: MessageAttachment[] | undefined) => AnnotationGroup[];
+//# sourceMappingURL=reference-attachment.d.ts.map

package/utils/reference-attachment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-attachment.d.ts","sourceRoot":"","sources":["../../src/utils/reference-attachment.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAE/E,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,+BAA+B,CAAC;AAEvC;;;GAGG;AACH,eAAO,MAAM,yBAAyB,GAAI,KAAK,iBAAiB,KAAG,OACrB,CAAC;AAE/C,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAID,iJAAiJ;AACjJ,eAAO,MAAM,qBAAqB,GAAI,KAAK,MAAM,KAAG,gBAAgB,GAAG,IAOtE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,GACvC,MAAM,iBAAiB,EAAE,GAAG,SAAS,KACpC,eAAe,EAyBjB,CAAC"}

package/utils/useAnnotations.d.ts

@@ -0,0 +1,7 @@
+import { Annotation, Message } from '@epam/ai-dial-chat-shared';
+/**
+ * Returns the resolved annotation list for an assistant message.
+ * Returns an empty array while streaming is in progress.
+ */
+export declare const useAnnotations: (message: Message, isStreaming: boolean) => Annotation[];
+//# sourceMappingURL=useAnnotations.d.ts.map

package/utils/useAnnotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAnnotations.d.ts","sourceRoot":"","sources":["../../src/utils/useAnnotations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAIrE;;;GAGG;AACH,eAAO,MAAM,cAAc,GACzB,SAAS,OAAO,EAChB,aAAa,OAAO,KACnB,UAAU,EAKZ,CAAC"}

package/utils/useCitationCard.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Manages open/close state and per-group active annotation index for citation
+ * cards within a single assistant message.
+ */
+export declare const useCitationCard: () => {
+    openPopup: (sourceUrl: string) => void;
+    closePopup: () => void;
+    setActiveIndex: (sourceUrl: string, index: number) => void;
+    isOpen: (sourceUrl: string) => boolean;
+    getActiveIndex: (sourceUrl: string) => number;
+};
+//# sourceMappingURL=useCitationCard.d.ts.map

package/utils/useCitationCard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCitationCard.d.ts","sourceRoot":"","sources":["../../src/utils/useCitationCard.ts"],"names":[],"mappings":"AAcA;;;GAGG;AACH,eAAO,MAAM,eAAe;2BAGgB,MAAM;;gCAQD,MAAM,SAAS,MAAM;wBAY5C,MAAM;gCACE,MAAM;CAKvC,CAAC"}