@mieweb/ui 0.10.0-dev.8 → 0.10.0-dev.9

package/dist/hooks/index.cjs

@@ -1,8 +1,9 @@
 'use strict';
 
-var chunkWNAA6CLE_cjs = require('../chunk-WNAA6CLE.cjs');
+var chunkAR7AKDM2_cjs = require('../chunk-AR7AKDM2.cjs');
 var chunkIXFC7LK2_cjs = require('../chunk-IXFC7LK2.cjs');
 var chunk2O7D6F67_cjs = require('../chunk-2O7D6F67.cjs');
+var chunkVPTASZ2O_cjs = require('../chunk-VPTASZ2O.cjs');
 var chunk7IKLGH3Z_cjs = require('../chunk-7IKLGH3Z.cjs');
 var chunkNPKPCYAT_cjs = require('../chunk-NPKPCYAT.cjs');
 require('../chunk-NUFUV43P.cjs');
@@ -21,51 +22,51 @@ require('../chunk-EUAMEVVI.cjs');
 
 Object.defineProperty(exports, "RTL_LOCALES", {
   enumerable: true,
-  get: function () { return chunkWNAA6CLE_cjs.RTL_LOCALES; }
+  get: function () { return chunkAR7AKDM2_cjs.RTL_LOCALES; }
 });
 Object.defineProperty(exports, "isRtlLocale", {
   enumerable: true,
-  get: function () { return chunkWNAA6CLE_cjs.isRtlLocale; }
+  get: function () { return chunkAR7AKDM2_cjs.isRtlLocale; }
 });
 Object.defineProperty(exports, "useCommandK", {
   enumerable: true,
-  get: function () { return chunkWNAA6CLE_cjs.useCommandK; }
+  get: function () { return chunkAR7AKDM2_cjs.useCommandK; }
 });
 Object.defineProperty(exports, "useDirection", {
   enumerable: true,
-  get: function () { return chunkWNAA6CLE_cjs.useDirection; }
+  get: function () { return chunkAR7AKDM2_cjs.useDirection; }
 });
 Object.defineProperty(exports, "useIsDesktop", {
   enumerable: true,
-  get: function () { return chunkWNAA6CLE_cjs.useIsDesktop; }
+  get: function () { return chunkAR7AKDM2_cjs.useIsDesktop; }
 });
 Object.defineProperty(exports, "useIsLargeDesktop", {
   enumerable: true,
-  get: function () { return chunkWNAA6CLE_cjs.useIsLargeDesktop; }
+  get: function () { return chunkAR7AKDM2_cjs.useIsLargeDesktop; }
 });
 Object.defineProperty(exports, "useIsMobile", {
   enumerable: true,
-  get: function () { return chunkWNAA6CLE_cjs.useIsMobile; }
+  get: function () { return chunkAR7AKDM2_cjs.useIsMobile; }
 });
 Object.defineProperty(exports, "useIsMobileOrTablet", {
   enumerable: true,
-  get: function () { return chunkWNAA6CLE_cjs.useIsMobileOrTablet; }
+  get: function () { return chunkAR7AKDM2_cjs.useIsMobileOrTablet; }
 });
 Object.defineProperty(exports, "useIsSmallTablet", {
   enumerable: true,
-  get: function () { return chunkWNAA6CLE_cjs.useIsSmallTablet; }
+  get: function () { return chunkAR7AKDM2_cjs.useIsSmallTablet; }
 });
 Object.defineProperty(exports, "useIsTablet", {
   enumerable: true,
-  get: function () { return chunkWNAA6CLE_cjs.useIsTablet; }
+  get: function () { return chunkAR7AKDM2_cjs.useIsTablet; }
 });
 Object.defineProperty(exports, "useKeyboardShortcut", {
   enumerable: true,
-  get: function () { return chunkWNAA6CLE_cjs.useKeyboardShortcut; }
+  get: function () { return chunkAR7AKDM2_cjs.useKeyboardShortcut; }
 });
 Object.defineProperty(exports, "useMediaQuery", {
   enumerable: true,
-  get: function () { return chunkWNAA6CLE_cjs.useMediaQuery; }
+  get: function () { return chunkAR7AKDM2_cjs.useMediaQuery; }
 });
 Object.defineProperty(exports, "useYouTubeHoverPreview", {
   enumerable: true,
@@ -75,6 +76,14 @@ Object.defineProperty(exports, "useTheme", {
   enumerable: true,
   get: function () { return chunk2O7D6F67_cjs.useTheme; }
 });
+Object.defineProperty(exports, "useStickToBottom", {
+  enumerable: true,
+  get: function () { return chunkVPTASZ2O_cjs.useStickToBottom; }
+});
+Object.defineProperty(exports, "useStreamEndedBelowFold", {
+  enumerable: true,
+  get: function () { return chunkVPTASZ2O_cjs.useStreamEndedBelowFold; }
+});
 Object.defineProperty(exports, "useScrollSpy", {
   enumerable: true,
   get: function () { return chunk7IKLGH3Z_cjs.useScrollSpy; }

package/dist/hooks/index.d.cts

@@ -319,6 +319,106 @@ 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. */
@@ -444,4 +544,4 @@ interface UseMediaTransportReturn {
  */
 declare function useMediaTransport(options?: UseMediaTransportOptions): UseMediaTransportReturn;
 
-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 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, useYouTubeHoverPreview };
+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.d.ts

@@ -319,6 +319,106 @@ 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. */
@@ -444,4 +544,4 @@ interface UseMediaTransportReturn {
  */
 declare function useMediaTransport(options?: UseMediaTransportOptions): UseMediaTransportReturn;
 
-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 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, useYouTubeHoverPreview };
+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,6 +1,7 @@
-export { RTL_LOCALES, isRtlLocale, useCommandK, useDirection, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsMobileOrTablet, useIsSmallTablet, useIsTablet, useKeyboardShortcut, useMediaQuery } from '../chunk-JHULS3EC.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';