@astra-kit/ui 0.0.0-stage → 1.0.0

package/dist/constants/select.js

@@ -0,0 +1,34 @@
+import { ARC_DURATION, ARC_EASE } from "../motion/arc-tokens.js";
+/** Minimum distance, in pixels, the option list keeps from the viewport edges. */
+export const SELECT_COLLISION_PADDING_PX = 12;
+/** Default Spanish placeholder, shown while no option is chosen. Arc's English default is "Select an option". */
+export const SELECT_DEFAULT_PLACEHOLDER = "Seleccioná una opción";
+const SELECT_ENTER_TWEEN = {
+	duration: ARC_DURATION.standard,
+	ease: [...ARC_EASE.enter]
+};
+const SELECT_EXIT_TWEEN = {
+	duration: ARC_DURATION.instant,
+	ease: [...ARC_EASE.standard]
+};
+/** Arc's option list: it grows 6px from the trigger edge at .97 and leaves halfway back at .98, both as tweens. */
+export const SELECT_MOTION = {
+	enterFrom: {
+		travel: 6,
+		scale: .97,
+		opacity: 0
+	},
+	enter: {
+		transform: SELECT_ENTER_TWEEN,
+		opacity: SELECT_ENTER_TWEEN
+	},
+	exitTo: {
+		travel: 3,
+		scale: .98,
+		opacity: 0
+	},
+	exit: {
+		transform: SELECT_EXIT_TWEEN,
+		opacity: SELECT_EXIT_TWEEN
+	}
+};

package/dist/constants/sidebar.d.ts

@@ -0,0 +1,9 @@
+/** Defines the cookie contract shared by the UI and server-side consumers. */
+/** Stable cookie key read by server entrypoints and written by the sidebar. */
+export declare const SIDEBAR_COOKIE_NAME = "sidebar_state";
+/** Serialized value representing expanded navigation. */
+export declare const SIDEBAR_COOKIE_OPEN_VALUE = "true";
+/** Serialized value representing collapsed navigation. */
+export declare const SIDEBAR_COOKIE_COLLAPSED_VALUE = "false";
+/** Preference lifetime in seconds, as required by the cookie max-age field. */
+export declare const SIDEBAR_COOKIE_MAX_AGE: number;

package/dist/constants/sidebar.js

@@ -0,0 +1,17 @@
+/** Defines the cookie contract shared by the UI and server-side consumers. */
+/** Number of days the navigation preference remains valid. */
+const SIDEBAR_COOKIE_MAX_AGE_DAYS = 7;
+/** Converts preference days into hours. */
+const SIDEBAR_COOKIE_MAX_AGE_HOURS_PER_DAY = 24;
+/** Converts preference hours into minutes. */
+const SIDEBAR_COOKIE_MAX_AGE_MINUTES_PER_HOUR = 60;
+/** Converts preference minutes into cookie max-age seconds. */
+const SIDEBAR_COOKIE_MAX_AGE_SECONDS_PER_MINUTE = 60;
+/** Stable cookie key read by server entrypoints and written by the sidebar. */
+export const SIDEBAR_COOKIE_NAME = "sidebar_state";
+/** Serialized value representing expanded navigation. */
+export const SIDEBAR_COOKIE_OPEN_VALUE = "true";
+/** Serialized value representing collapsed navigation. */
+export const SIDEBAR_COOKIE_COLLAPSED_VALUE = "false";
+/** Preference lifetime in seconds, as required by the cookie max-age field. */
+export const SIDEBAR_COOKIE_MAX_AGE = SIDEBAR_COOKIE_MAX_AGE_SECONDS_PER_MINUTE * SIDEBAR_COOKIE_MAX_AGE_MINUTES_PER_HOUR * SIDEBAR_COOKIE_MAX_AGE_HOURS_PER_DAY * SIDEBAR_COOKIE_MAX_AGE_DAYS;

package/dist/constants/skeleton.d.ts

@@ -0,0 +1,17 @@
+/** Defaults and tuning of Arc's Skeleton placeholder. */
+/** Default Spanish label announced while the composed placeholder is busy. */
+export declare const SKELETON_DEFAULT_LABEL = "Cargando contenido";
+/** Text lines the composed placeholder draws when `lines` is not set. */
+export declare const SKELETON_DEFAULT_LINES = 3;
+/** Bounds of `lines`, so a placeholder never collapses or turns into a wall of bars. */
+export declare const SKELETON_LINE_LIMITS: {
+    readonly min: 1;
+    readonly max: 6;
+};
+/**
+ * After loading flips, resizes inside this window spring to the new height; later resizes (a font swap, a parent
+ * reflow) follow at once.
+ */
+export declare const SKELETON_MORPH_WINDOW_MS = 120;
+/** Vertical travel, in pixels, of revealed content rising into place. */
+export declare const SKELETON_REVEAL_OFFSET_PX = 4;

package/dist/constants/skeleton.js

@@ -0,0 +1,17 @@
+/** Defaults and tuning of Arc's Skeleton placeholder. */
+/** Default Spanish label announced while the composed placeholder is busy. */
+export const SKELETON_DEFAULT_LABEL = "Cargando contenido";
+/** Text lines the composed placeholder draws when `lines` is not set. */
+export const SKELETON_DEFAULT_LINES = 3;
+/** Bounds of `lines`, so a placeholder never collapses or turns into a wall of bars. */
+export const SKELETON_LINE_LIMITS = {
+	min: 1,
+	max: 6
+};
+/**
+* After loading flips, resizes inside this window spring to the new height; later resizes (a font swap, a parent
+* reflow) follow at once.
+*/
+export const SKELETON_MORPH_WINDOW_MS = 120;
+/** Vertical travel, in pixels, of revealed content rising into place. */
+export const SKELETON_REVEAL_OFFSET_PX = 4;

package/dist/constants/split-button.d.ts

@@ -0,0 +1,7 @@
+/** `primary` for the main action of a surface, `secondary` for a quieter, smaller one. */
+export type SplitButtonVariant = "primary" | "secondary";
+/** Height of both halves for each variant: the secondary split button is compact, as in Arc. */
+export declare const SPLIT_BUTTON_SIZE_BY_VARIANT: {
+    readonly primary: "md";
+    readonly secondary: "sm";
+};

package/dist/constants/split-button.js

@@ -0,0 +1,5 @@
+/** Height of both halves for each variant: the secondary split button is compact, as in Arc. */
+export const SPLIT_BUTTON_SIZE_BY_VARIANT = {
+	primary: "md",
+	secondary: "sm"
+};

package/dist/constants/switch.d.ts

@@ -0,0 +1,33 @@
+/** Tuning of Arc's Switch thumb, adapted from Arc (https://uiarc.dev, MIT License, see THIRD_PARTY_NOTICES.md). */
+/**
+ * Thumb geometry on Arc's 42 by 24 track, in pixels: its resting width and how far it travels, which is the track's
+ * inner width minus the thumb. Keep in sync with the track and thumb sizes in `switch.tsx`.
+ */
+export declare const SWITCH_THUMB_GEOMETRY_PX: {
+    readonly size: 18;
+    readonly travel: 18;
+};
+/** How far, in pixels, the thumb widens toward the other side while it is held down. */
+export declare const SWITCH_PRESS_STRETCH_PX = 5;
+/** Critically damped glide: the thumb lands on its end without overshooting the state it reports. */
+export declare const SWITCH_THUMB_GLIDE_SPRING: {
+    readonly type: "spring";
+    readonly visualDuration: 0.3;
+    readonly bounce: 0;
+};
+/**
+ * Brief horizontal stretch played when the state changes without a press (a controlled update or a label click), so
+ * the thumb reads as moving mass rather than a sliding dot.
+ */
+export declare const SWITCH_CHANGE_STRETCH: {
+    readonly scaleX: readonly [1, 1.16, 1];
+    readonly duration: 0.34;
+    readonly times: readonly [0, 0.4, 1];
+    readonly ease: readonly ["easeOut", "easeInOut"];
+};
+/** Window, in milliseconds, after a pointer or Space release in which a state change counts as caused by that press. */
+export declare const SWITCH_PRESS_RELEASE_WINDOW_MS = 250;
+/** Key that toggles a focused switch and stretches its thumb while held. */
+export declare const SWITCH_TOGGLE_KEY = " ";
+/** Mouse button that presses the switch: the primary one. */
+export declare const SWITCH_PRIMARY_POINTER_BUTTON = 0;

package/dist/constants/switch.js

@@ -0,0 +1,41 @@
+/** Tuning of Arc's Switch thumb, adapted from Arc (https://uiarc.dev, MIT License, see THIRD_PARTY_NOTICES.md). */
+/**
+* Thumb geometry on Arc's 42 by 24 track, in pixels: its resting width and how far it travels, which is the track's
+* inner width minus the thumb. Keep in sync with the track and thumb sizes in `switch.tsx`.
+*/
+export const SWITCH_THUMB_GEOMETRY_PX = {
+	size: 18,
+	travel: 18
+};
+/** How far, in pixels, the thumb widens toward the other side while it is held down. */
+export const SWITCH_PRESS_STRETCH_PX = 5;
+/** Critically damped glide: the thumb lands on its end without overshooting the state it reports. */
+export const SWITCH_THUMB_GLIDE_SPRING = {
+	type: "spring",
+	visualDuration: .3,
+	bounce: 0
+};
+/**
+* Brief horizontal stretch played when the state changes without a press (a controlled update or a label click), so
+* the thumb reads as moving mass rather than a sliding dot.
+*/
+export const SWITCH_CHANGE_STRETCH = {
+	scaleX: [
+		1,
+		1.16,
+		1
+	],
+	duration: .34,
+	times: [
+		0,
+		.4,
+		1
+	],
+	ease: ["easeOut", "easeInOut"]
+};
+/** Window, in milliseconds, after a pointer or Space release in which a state change counts as caused by that press. */
+export const SWITCH_PRESS_RELEASE_WINDOW_MS = 250;
+/** Key that toggles a focused switch and stretches its thumb while held. */
+export const SWITCH_TOGGLE_KEY = " ";
+/** Mouse button that presses the switch: the primary one. */
+export const SWITCH_PRIMARY_POINTER_BUTTON = 0;

package/dist/constants/tabs.d.ts

@@ -0,0 +1,17 @@
+/** Tuning of Arc's Tabs: directional panel motion, height morph and active-tab reveal. */
+/** Sign of the travel between two tabs: forward when the new tab sits after the previous one. */
+export declare const TABS_DIRECTION: {
+    readonly forward: 1;
+    readonly backward: -1;
+};
+/** Distance, in px, an entering panel slides in from and a leaving panel slides out to. */
+export declare const TABS_PANEL_OFFSET_PX: {
+    readonly enter: 8;
+    readonly exit: 6;
+};
+/** Fade-out, in seconds, of a leaving panel when motion is reduced. */
+export declare const TABS_PANEL_REDUCED_EXIT_DURATION_S = 0.1;
+/** Height differences up to this many px between panels jump instead of morphing. */
+export declare const TABS_PANEL_HEIGHT_TOLERANCE_PX = 1;
+/** Space, in px, kept between a revealed tab and the scrolled list edge: the list padding. */
+export declare const TABS_REVEAL_MARGIN_PX = 4;

package/dist/constants/tabs.js

@@ -0,0 +1,17 @@
+/** Tuning of Arc's Tabs: directional panel motion, height morph and active-tab reveal. */
+/** Sign of the travel between two tabs: forward when the new tab sits after the previous one. */
+export const TABS_DIRECTION = {
+	forward: 1,
+	backward: -1
+};
+/** Distance, in px, an entering panel slides in from and a leaving panel slides out to. */
+export const TABS_PANEL_OFFSET_PX = {
+	enter: 8,
+	exit: 6
+};
+/** Fade-out, in seconds, of a leaving panel when motion is reduced. */
+export const TABS_PANEL_REDUCED_EXIT_DURATION_S = .1;
+/** Height differences up to this many px between panels jump instead of morphing. */
+export const TABS_PANEL_HEIGHT_TOLERANCE_PX = 1;
+/** Space, in px, kept between a revealed tab and the scrolled list edge: the list padding. */
+export const TABS_REVEAL_MARGIN_PX = 4;

package/dist/constants/toast.d.ts

@@ -0,0 +1,3 @@
+/** Contract with the toast layer rendered by `ThemedToaster` (Sonner). */
+/** Selector of the list Sonner renders for each toast position, the outermost element of the toast layer. */
+export declare const TOAST_LAYER_SELECTOR = "[data-sonner-toaster]";

package/dist/constants/toast.js

@@ -0,0 +1,3 @@
+/** Contract with the toast layer rendered by `ThemedToaster` (Sonner). */
+/** Selector of the list Sonner renders for each toast position, the outermost element of the toast layer. */
+export const TOAST_LAYER_SELECTOR = "[data-sonner-toaster]";

package/dist/constants/tooltip.d.ts

@@ -0,0 +1,13 @@
+import type { ArcFloatingMotion } from "../motion/arc-floating-slot.js";
+/** Milliseconds of hover or focus before the first tooltip opens. */
+export declare const TOOLTIP_OPEN_DELAY_MS = 250;
+/** While a tooltip is open, and this many milliseconds after the last one closes, the next opens at once and only fades. */
+export declare const TOOLTIP_SKIP_WINDOW_MS = 300;
+/** Gap, in px, between the bubble and its trigger. */
+export declare const TOOLTIP_SIDE_OFFSET_PX = 8;
+/** Distance, in px, the bubble keeps from the viewport edges before it flips or shifts. */
+export declare const TOOLTIP_COLLISION_PADDING_PX = 12;
+/** The first tooltip rises 3px from its trigger while it scales up from .97. */
+export declare const TOOLTIP_MOTION: ArcFloatingMotion;
+/** Within the skip window the next tooltip only fades in, on the instant timing. */
+export declare const TOOLTIP_INSTANT_MOTION: ArcFloatingMotion;

package/dist/constants/tooltip.js

@@ -0,0 +1,52 @@
+import { ARC_DURATION, ARC_EASE } from "../motion/arc-tokens.js";
+/** Milliseconds of hover or focus before the first tooltip opens. */
+export const TOOLTIP_OPEN_DELAY_MS = 250;
+/** While a tooltip is open, and this many milliseconds after the last one closes, the next opens at once and only fades. */
+export const TOOLTIP_SKIP_WINDOW_MS = 300;
+/** Gap, in px, between the bubble and its trigger. */
+export const TOOLTIP_SIDE_OFFSET_PX = 8;
+/** Distance, in px, the bubble keeps from the viewport edges before it flips or shifts. */
+export const TOOLTIP_COLLISION_PADDING_PX = 12;
+const enterTween = {
+	duration: ARC_DURATION.fast,
+	ease: [...ARC_EASE.enter]
+};
+const instantTween = {
+	duration: ARC_DURATION.instant,
+	ease: [...ARC_EASE.standard]
+};
+/** The first tooltip rises 3px from its trigger while it scales up from .97. */
+export const TOOLTIP_MOTION = {
+	enterFrom: {
+		travel: 3,
+		scale: .97,
+		opacity: 0
+	},
+	enter: {
+		transform: enterTween,
+		opacity: enterTween
+	},
+	exitTo: {
+		travel: 0,
+		scale: .98,
+		opacity: 0
+	},
+	exit: {
+		transform: instantTween,
+		opacity: instantTween
+	}
+};
+/** Within the skip window the next tooltip only fades in, on the instant timing. */
+export const TOOLTIP_INSTANT_MOTION = {
+	enterFrom: {
+		travel: 0,
+		scale: 1,
+		opacity: 0
+	},
+	enter: {
+		transform: instantTween,
+		opacity: instantTween
+	},
+	exitTo: TOOLTIP_MOTION.exitTo,
+	exit: TOOLTIP_MOTION.exit
+};

package/dist/hooks/use-horizontal-swipe.d.ts

@@ -0,0 +1,23 @@
+/** Recognizes one-finger horizontal swipes on touch surfaces such as pagers and calendars. */
+import { type TouchEvent } from "react";
+import { type HorizontalSwipeDirection } from "../lib/horizontal-swipe.js";
+/**
+ * Touch handlers to spread on the swipe surface.
+ */
+export type HorizontalSwipeHandlers = {
+    onTouchCancel: () => void;
+    onTouchEnd: (event: TouchEvent<HTMLElement>) => void;
+    onTouchStart: (event: TouchEvent<HTMLElement>) => void;
+};
+/**
+ * Detects horizontal one-finger swipes. Touch events are used instead of
+ * Pointer Events because browsers fire `pointercancel` as soon as they start
+ * scrolling, and WebKit (iOS Safari and every iOS browser) has only partial
+ * `touch-action` support to prevent it, while `touchend` is delivered on
+ * both engines. The handlers never call `preventDefault`, so native vertical
+ * scrolling and pinch-zoom keep working; mouse drags never trigger a swipe.
+ *
+ * @param onSwipe - Called once per recognised swipe.
+ * @returns Handlers for the swipe surface.
+ */
+export declare function useHorizontalSwipe(onSwipe: (direction: HorizontalSwipeDirection) => void): HorizontalSwipeHandlers;

package/dist/hooks/use-horizontal-swipe.js

@@ -0,0 +1,80 @@
+"use client";
+import { c as _c } from "react/compiler-runtime";
+/** Recognizes one-finger horizontal swipes on touch surfaces such as pagers and calendars. */
+import { useRef } from "react";
+import { resolveHorizontalSwipe } from "../lib/horizontal-swipe.js";
+/**
+* Detects horizontal one-finger swipes. Touch events are used instead of
+* Pointer Events because browsers fire `pointercancel` as soon as they start
+* scrolling, and WebKit (iOS Safari and every iOS browser) has only partial
+* `touch-action` support to prevent it, while `touchend` is delivered on
+* both engines. The handlers never call `preventDefault`, so native vertical
+* scrolling and pinch-zoom keep working; mouse drags never trigger a swipe.
+*
+* @param onSwipe - Called once per recognised swipe.
+* @returns Handlers for the swipe surface.
+*/
+export function useHorizontalSwipe(onSwipe) {
+	const $ = _c(6);
+	const swipeStartRef = useRef(null);
+	let t0;
+	if ($[0] === Symbol.for("react.memo_cache_sentinel")) {
+		t0 = () => {
+			swipeStartRef.current = null;
+		};
+		$[0] = t0;
+	} else {
+		t0 = $[0];
+	}
+	let t1;
+	if ($[1] !== onSwipe) {
+		t1 = (event) => {
+			const swipeStart = swipeStartRef.current;
+			const endTouch = swipeStart ? Array.from(event.changedTouches).find((touch) => touch.identifier === swipeStart.identifier) : undefined;
+			swipeStartRef.current = null;
+			if (!swipeStart || !endTouch) {
+				return;
+			}
+			const direction = resolveHorizontalSwipe({
+				deltaX: endTouch.clientX - swipeStart.x,
+				deltaY: endTouch.clientY - swipeStart.y,
+				durationMs: event.timeStamp - swipeStart.startTime
+			});
+			if (direction) {
+				onSwipe(direction);
+			}
+		};
+		$[1] = onSwipe;
+		$[2] = t1;
+	} else {
+		t1 = $[2];
+	}
+	let t2;
+	if ($[3] === Symbol.for("react.memo_cache_sentinel")) {
+		t2 = (event_0) => {
+			const [firstTouch] = Array.from(event_0.touches);
+			swipeStartRef.current = event_0.touches.length === 1 && firstTouch ? {
+				identifier: firstTouch.identifier,
+				startTime: event_0.timeStamp,
+				x: firstTouch.clientX,
+				y: firstTouch.clientY
+			} : null;
+		};
+		$[3] = t2;
+	} else {
+		t2 = $[3];
+	}
+	let t3;
+	if ($[4] !== t1) {
+		t3 = {
+			onTouchCancel: t0,
+			onTouchEnd: t1,
+			onTouchStart: t2
+		};
+		$[4] = t1;
+		$[5] = t3;
+	} else {
+		t3 = $[5];
+	}
+	return t3;
+}

package/dist/hooks/use-is-hydrated.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Hydration store: the server snapshot is `false` and the client snapshot is
+ * `true`, so the first client render still matches the server markup and the
+ * component learns it is hydrated on the very next render without an effect.
+ */
+export declare function useIsHydrated(): boolean;

package/dist/hooks/use-is-hydrated.js

@@ -0,0 +1,20 @@
+"use client";
+/** Tells hydrated client renders apart from server and hydration renders without an effect. */
+import { useSyncExternalStore } from "react";
+function subscribeToNothing() {
+	return () => undefined;
+}
+function getHydratedSnapshot() {
+	return true;
+}
+function getServerHydratedSnapshot() {
+	return false;
+}
+/**
+* Hydration store: the server snapshot is `false` and the client snapshot is
+* `true`, so the first client render still matches the server markup and the
+* component learns it is hydrated on the very next render without an effect.
+*/
+export function useIsHydrated() {
+	return useSyncExternalStore(subscribeToNothing, getHydratedSnapshot, getServerHydratedSnapshot);
+}

package/dist/hooks/use-mobile.d.ts

@@ -0,0 +1 @@
+export declare function useIsMobile(): boolean;

package/dist/hooks/use-mobile.js

@@ -0,0 +1,19 @@
+import * as React from "react";
+/** Viewport width in CSS pixels at which desktop navigation begins. */
+const MOBILE_BREAKPOINT = 768;
+function subscribeToMobileBreakpoint(onStoreChange) {
+	const mediaQueryList = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
+	mediaQueryList.addEventListener("change", onStoreChange);
+	return () => {
+		mediaQueryList.removeEventListener("change", onStoreChange);
+	};
+}
+function getMobileSnapshot() {
+	return window.innerWidth < MOBILE_BREAKPOINT;
+}
+function getServerMobileSnapshot() {
+	return false;
+}
+export function useIsMobile() {
+	return React.useSyncExternalStore(subscribeToMobileBreakpoint, getMobileSnapshot, getServerMobileSnapshot);
+}

package/dist/hooks/use-prefers-reduced-motion.d.ts

@@ -0,0 +1,2 @@
+/** Returns a live preference for animations that cannot be controlled with CSS alone. */
+export declare function usePrefersReducedMotion(): boolean;

package/dist/hooks/use-prefers-reduced-motion.js

@@ -0,0 +1,27 @@
+"use client";
+/** Reads motion preferences without changing the initial server/hydration markup. */
+import { useSyncExternalStore } from "react";
+import { REDUCED_MOTION_QUERY } from "../constants/motion.js";
+/** Subscribes to preference changes, including browsers exposing the legacy media API. */
+function subscribe(onChange) {
+	if (typeof window === "undefined" || typeof window.matchMedia !== "function") return () => {};
+	const query = window.matchMedia(REDUCED_MOTION_QUERY);
+	if (typeof query.addEventListener === "function") {
+		query.addEventListener("change", onChange);
+		return () => query.removeEventListener("change", onChange);
+	}
+	query.addListener?.(onChange);
+	return () => query.removeListener?.(onChange);
+}
+/** Resolves the current browser setting while tolerating non-browser test environments. */
+function getSnapshot() {
+	return typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia(REDUCED_MOTION_QUERY).matches;
+}
+/** Keeps the initial client tree consistent with the server-rendered tree. */
+function getServerSnapshot() {
+	return false;
+}
+/** Returns a live preference for animations that cannot be controlled with CSS alone. */
+export function usePrefersReducedMotion() {
+	return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}

package/dist/hooks/use-rich-link-editor.d.ts

@@ -0,0 +1,55 @@
+/** Owns the state of `RichLinkEditor`: content, tracked links, popover and selection. */
+import { type ClipboardEvent, type FormEvent, type KeyboardEvent } from "react";
+import { RICH_LINK_POPOVER_MODE } from "../lib/rich-text/link-markdown-constants.js";
+import type { ActiveRichPreviewLink, RichLink, RichPreviewSegment } from "../lib/rich-text/link-markdown-types.js";
+type RichLinkPopoverMode = (typeof RICH_LINK_POPOVER_MODE)[keyof typeof RICH_LINK_POPOVER_MODE];
+/** Plain-text content plus tracked links, used to snapshot/restore the editor. */
+export type RichLinkEditorDisplayState = {
+    content: string;
+    links: RichLink[];
+};
+type UseRichLinkEditorOptions = {
+    /** Persisted markdown loaded as the initial editor value. */
+    initialMarkdown?: string;
+    /** Called whenever the author changes the content (e.g. to clear errors). */
+    onContentChange?: () => void;
+};
+/** Imperative + reactive API exposed by `useRichLinkEditor` to the editor UI. */
+export type RichLinkEditorController = {
+    setEditorElement: (node: HTMLDivElement | null) => void;
+    segments: RichPreviewSegment[];
+    hasContent: boolean;
+    content: string;
+    activeLink: ActiveRichPreviewLink | null;
+    linkTextInput: string;
+    linkUrlInput: string;
+    popoverMode: RichLinkPopoverMode;
+    /** Whether the popover draft has visible text and an http(s) URL, so it can be saved. */
+    isLinkEditValid: boolean;
+    /** Whether the author typed a URL that cannot become a safe http(s) link. */
+    hasInvalidLinkUrl: boolean;
+    setLinkTextInput: (value: string) => void;
+    setLinkUrlInput: (value: string) => void;
+    setPopoverMode: (mode: RichLinkPopoverMode) => void;
+    handleBeforeInput: (event: FormEvent<HTMLDivElement>) => void;
+    handleInput: (event: FormEvent<HTMLDivElement>) => void;
+    handleKeyDown: (event: KeyboardEvent<HTMLDivElement>) => void;
+    handlePaste: (event: ClipboardEvent<HTMLDivElement>) => void;
+    openLinkPopover: (segment: ActiveRichPreviewLink) => void;
+    closeLinkPopover: () => void;
+    removeLink: (segment: ActiveRichPreviewLink) => void;
+    saveLinkEdit: (segment: ActiveRichPreviewLink) => void;
+    serialize: () => string;
+    reset: (markdown?: string) => void;
+    getDisplayState: () => RichLinkEditorDisplayState;
+    loadFromDisplay: (state: RichLinkEditorDisplayState) => void;
+};
+/**
+ * Controls a rich link editor backed by a `contentEditable` element: it owns the
+ * plain-text content, the tracked explicit/suppressed links, the link popover
+ * state, and the selection bookkeeping, and exposes serialize/reset/snapshot
+ * helpers so a feature can persist or restore the value. The DOM rendering lives
+ * in `RichLinkEditor`.
+ */
+export declare function useRichLinkEditor(options?: UseRichLinkEditorOptions): RichLinkEditorController;
+export {};