@mieweb/ui 0.10.0-dev.1 → 0.10.0-dev.11

package/dist/hooks/index.d.ts

@@ -319,6 +319,146 @@ declare function dragIndicatorClasses(drag: Pick<UseDragReorderReturn, 'dragging
  */
 declare function useLiveAnnouncement(): [string, (message: string) => void];
 
+/**
+ * Options for {@link useStickToBottom}.
+ */
+interface UseStickToBottomOptions {
+    /**
+     * Distance from the bottom (px) within which the user still counts as "at
+     * the bottom" — small offsets from rounding or momentum scrolling shouldn't
+     * break pinning.
+     */
+    threshold?: number;
+    /**
+     * Disable all behavior (listeners and observers detach). Useful when the
+     * scroll container anchors somewhere other than the bottom (e.g. a
+     * newest-first feed).
+     */
+    disabled?: boolean;
+}
+interface UseStickToBottomReturn {
+    /** Attach to the scrollable container. */
+    containerRef: React.RefObject<HTMLDivElement | null>;
+    /**
+     * Attach to the element wrapping the container's content. Its growth (e.g.
+     * a streaming message) re-pins the scroll while the user is at the bottom.
+     */
+    contentRef: React.RefObject<HTMLDivElement | null>;
+    /** Whether the user is currently at (or within `threshold` of) the bottom. */
+    isAtBottom: boolean;
+    /** Scroll to the bottom and resume pinning. */
+    scrollToBottom: (behavior?: ScrollBehavior) => void;
+    /**
+     * Scroll so `target`'s top aligns with the viewport top and enter “reading”
+     * mode: content growing past the fold no longer auto-follows, so the reader
+     * consumes the response at their own pace (the ChatGPT/Claude send UX).
+     * Following resumes when they explicitly return to the bottom — a
+     * jump-to-bottom click (`scrollToBottom`) or scrolling there by hand.
+     */
+    anchorToTurnStart: (target: HTMLElement, behavior?: ScrollBehavior) => void;
+    /**
+     * Scroll to the bottom only while actually following (at the bottom and not
+     * in reading mode). Returns whether it scrolled — hosts use this to decide
+     * between following an appended message and raising a “new messages” hint.
+     */
+    followIfPinned: (behavior?: ScrollBehavior) => boolean;
+    /**
+     * Hold the current position: enter reading mode without scrolling, so an
+     * incoming stream fills below the fold instead of pushing the view up.
+     * Call right after a streaming message appends (optionally after revealing
+     * its first line with `followIfPinned`). Following resumes exactly as after
+     * `anchorToTurnStart`: an explicit `scrollToBottom` or the reader returning
+     * to the bottom by hand.
+     */
+    stopFollowing: () => void;
+}
+/**
+ * Keeps a scroll container pinned to its bottom edge while the user is there,
+ * and — crucially — leaves the scroll position alone once they scroll up.
+ *
+ * Designed for chat threads with streaming responses:
+ * - While the user is at the bottom, content growth (new tokens, new
+ *   messages) and container resizes (on-screen keyboard, growing composer)
+ *   keep the newest content in view via a `ResizeObserver` on both the
+ *   content and the container.
+ * - Once the user scrolls up, nothing moves until they return to the bottom
+ *   themselves or the host calls `scrollToBottom` (e.g. a jump-to-bottom
+ *   button, or an outgoing message from the local user).
+ *
+ * The hook only pins; *when* to force a scroll (own message sent, thread
+ * switched) stays a host decision through `scrollToBottom`,
+ * `anchorToTurnStart` (ChatGPT-style: scroll a fresh turn to the viewport top
+ * and pause following while the reader digests the reply), and
+ * `followIfPinned` (follow an append only while actually at the bottom).
+ *
+ * @example
+ * ```tsx
+ * const { containerRef, contentRef, isAtBottom, scrollToBottom } =
+ *   useStickToBottom();
+ * return (
+ *   <div className="relative min-h-0 flex-1">
+ *     <div ref={containerRef} className="h-full overflow-y-auto">
+ *       <div ref={contentRef}>{rows}</div>
+ *     </div>
+ *     {!isAtBottom && <JumpToBottom onClick={() => scrollToBottom('smooth')} />}
+ *   </div>
+ * );
+ * ```
+ */
+declare function useStickToBottom({ threshold, disabled, }?: UseStickToBottomOptions): UseStickToBottomReturn;
+/**
+ * Companion to {@link useStickToBottom}: fires `onEnded` when the newest
+ * message finishes streaming while the reader is away from the bottom — the
+ * end of the reply landed below the fold, so the jump-to-bottom button should
+ * upgrade to its “new messages” hint. When the whole reply fit above the fold
+ * (the reader is still at the bottom), `onEndedAtBottom` fires instead so the
+ * host can exit the stream's hold and resume following (`scrollToBottom`).
+ */
+declare function useStreamEndedBelowFold(newest: {
+    id: string;
+    status?: string;
+} | undefined, isAtBottom: boolean, onEnded: () => void, onEndedAtBottom?: () => void): void;
+
+type HoverPreviewState = 'idle' | 'loading' | 'playing';
+interface UseYouTubeHoverPreviewOptions {
+    /** Hover dwell before the player mounts. Default 600ms. */
+    dwellMs?: number;
+    /** Player host. Default `https://www.youtube-nocookie.com`. */
+    host?: string;
+    /** Disable entirely (e.g. when the card has no YouTube id). */
+    enabled?: boolean;
+}
+interface UseYouTubeHoverPreviewReturn {
+    /** Lifecycle phase of the muted preview. */
+    preview: HoverPreviewState;
+    /** Normalised playback position (0–1) for a timeline bar. */
+    progress: number;
+    /** Attach to the element the muted iframe should fill. */
+    hostRef: React.RefObject<HTMLDivElement | null>;
+    /** Wire to the hover target's `onMouseEnter` / `onFocus`. */
+    handleEnter: () => void;
+    /** Wire to the hover target's `onMouseLeave` / `onBlur` (and any manual reset). */
+    stopPreview: () => void;
+}
+/**
+ * Drives a muted, looping YouTube hover preview for a single `youtubeId` — the
+ * "silent autoplay on dwell" pattern from YouTube's own grid. After a short
+ * hover dwell a muted player is mounted lazily inside `hostRef`; `progress`
+ * tracks playback for a timeline bar; everything tears down on leave so only
+ * one preview is ever live. Honours `prefers-reduced-motion` and skips
+ * pointer-less (touch) inputs.
+ *
+ * @example
+ * ```tsx
+ * const { preview, progress, hostRef, handleEnter, stopPreview } =
+ *   useYouTubeHoverPreview('dQw4w9WgXcQ');
+ * <a onMouseEnter={handleEnter} onMouseLeave={stopPreview}>
+ *   <div ref={hostRef} className={preview === 'playing' ? 'opacity-100' : 'opacity-0'} />
+ * </a>
+ * ```
+ */
+declare function useYouTubeHoverPreview(youtubeId: string | undefined, { dwellMs, host, enabled, }?: UseYouTubeHoverPreviewOptions): UseYouTubeHoverPreviewReturn;
+
 type MediaTransportState = 'idle' | 'loading' | 'playing' | 'paused' | 'error';
 interface UseMediaTransportOptions {
     /** Fired on every native `timeupdate` and on metadata load, in milliseconds. */
@@ -404,4 +544,4 @@ interface UseMediaTransportReturn {
  */
 declare function useMediaTransport(options?: UseMediaTransportOptions): UseMediaTransportReturn;
 
-export { type Direction, type DragOverState, type KeyboardShortcutOptions, type MediaTransportState, RTL_LOCALES, type UseDragReorderOptions, type UseDragReorderReturn, type UseMediaTransportOptions, type UseMediaTransportReturn, type UseScrollSpyOptions, type UseScrollSpyReturn, dragIndicatorClasses, isDarkMode, isRtlLocale, reorderIds, useClickOutside, useCommandK, useDirection, useDragReorder, useEscapeKey, useFocusTrap, useIsDarkMode, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsMobileOrTablet, useIsSmallTablet, useIsTablet, useKeyboardShortcut, useLiveAnnouncement, useMediaQuery, useMediaTransport, usePrefersReducedMotion, useScrollSpy };
+export { type Direction, type DragOverState, type HoverPreviewState, type KeyboardShortcutOptions, type MediaTransportState, RTL_LOCALES, type UseDragReorderOptions, type UseDragReorderReturn, type UseMediaTransportOptions, type UseMediaTransportReturn, type UseScrollSpyOptions, type UseScrollSpyReturn, type UseStickToBottomOptions, type UseStickToBottomReturn, type UseYouTubeHoverPreviewOptions, type UseYouTubeHoverPreviewReturn, dragIndicatorClasses, isDarkMode, isRtlLocale, reorderIds, useClickOutside, useCommandK, useDirection, useDragReorder, useEscapeKey, useFocusTrap, useIsDarkMode, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsMobileOrTablet, useIsSmallTablet, useIsTablet, useKeyboardShortcut, useLiveAnnouncement, useMediaQuery, useMediaTransport, usePrefersReducedMotion, useScrollSpy, useStickToBottom, useStreamEndedBelowFold, useYouTubeHoverPreview };

package/dist/hooks/index.js

@@ -1,16 +1,18 @@
-export { RTL_LOCALES, isRtlLocale, useCommandK, useDirection, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsMobileOrTablet, useIsSmallTablet, useIsTablet, useKeyboardShortcut, useMediaQuery } from '../chunk-24SEAAOH.js';
+export { RTL_LOCALES, isRtlLocale, useCommandK, useDirection, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsMobileOrTablet, useIsSmallTablet, useIsTablet, useKeyboardShortcut, useMediaQuery } from '../chunk-AWJBOND5.js';
+export { useYouTubeHoverPreview } from '../chunk-POWS35OT.js';
 export { useTheme } from '../chunk-KJZNEVYM.js';
+export { useStickToBottom, useStreamEndedBelowFold } from '../chunk-BM35CACB.js';
 export { useScrollSpy } from '../chunk-WBGUYSWY.js';
 export { DEFAULT_FILLER_WORDS, DEFAULT_MIN_SILENCE_MS, DEFAULT_NL_SILENCE_MS, buildPlaybackSegments, getSpeedAtIndex, initEditableWords, insertSilences, useTranscriptEdits } from '../chunk-UUI7WXI5.js';
 import '../chunk-6CGM5H4J.js';
 export { useMediaTransport } from '../chunk-SQHMGT4W.js';
 export { dragIndicatorClasses, reorderIds, useDragReorder, useLiveAnnouncement } from '../chunk-7ZVTLTJF.js';
-export { usePrefersReducedMotion } from '../chunk-HB7C7NB5.js';
+export { useClickOutside } from '../chunk-62ZOA6PX.js';
+export { useAnchoredPosition } from '../chunk-WSNMQQ4P.js';
 export { useFocusTrap } from '../chunk-4SMSH4OY.js';
 export { useEscapeKey } from '../chunk-T4ME7QCT.js';
 import '../chunk-VSQF22GL.js';
-export { useClickOutside } from '../chunk-62ZOA6PX.js';
-export { useAnchoredPosition } from '../chunk-WSNMQQ4P.js';
+export { usePrefersReducedMotion } from '../chunk-HB7C7NB5.js';
 export { isDarkMode, useIsDarkMode } from '../chunk-RUGHNFQG.js';
 import '../chunk-PX6F3LHL.js';
 //# sourceMappingURL=index.js.map