@mieweb/ui 0.10.0-dev.10 → 0.10.0-dev.12

package/dist/hooks/index.d.cts

@@ -1,45 +1,28 @@
-export { R as ResolvedTheme, T as Theme, u as useTheme } from '../useTheme-B9SWu6ui.cjs';
 import * as React from 'react';
 import { RefObject } from 'react';
-export { A as AnchoredPlacement, U as UseAnchoredPositionOptions, a as UseAnchoredPositionReturn, u as useAnchoredPosition } from '../useAnchoredPosition-CKwLSQW8.cjs';
-export { D as DEFAULT_FILLER_WORDS, a as DEFAULT_MIN_SILENCE_MS, b as DEFAULT_NL_SILENCE_MS, F as FillerAnalysis, S as SilenceThresholdCount, T as TranscriptClipboard, c as TranscriptEditStats, U as UseTranscriptEditsOptions, d as UseTranscriptEditsResult, e as buildPlaybackSegments, g as getSpeedAtIndex, i as initEditableWords, f as insertSilences, u as useTranscriptEdits } from '../useTranscriptEdits-CGzlemHT.cjs';
-import '../transcript-Cg7uSW-C.cjs';
 
-interface UseScrollSpyOptions {
-    /** CSS selector for the elements to observe (e.g. 'h2, h3, h4') */
-    selectors?: string;
-    /** Explicit list of element IDs to observe (alternative to selectors) */
-    ids?: string[];
-    /** IntersectionObserver root margin (default: '0px 0px -60% 0px') */
-    rootMargin?: string;
-    /** IntersectionObserver threshold (default: 0) */
-    threshold?: number | number[];
-    /** Scroll container element ref. Defaults to document viewport. */
-    root?: RefObject<HTMLElement | null>;
-    /** Whether the hook is active (default: true) */
-    enabled?: boolean;
-}
-interface UseScrollSpyReturn {
-    /** The ID of the currently active (in-view) element */
-    activeId: string | null;
-}
+type Theme = 'light' | 'dark' | 'system';
+type ResolvedTheme = 'light' | 'dark';
 /**
- * Tracks which section is currently in the viewport using IntersectionObserver.
- * Pairs naturally with `TableOfContents` to highlight the active heading.
+ * Hook for managing theme state with localStorage persistence and system preference support.
  *
  * @example
  * ```tsx
- * function DocsPage() {
- *   const { activeId } = useScrollSpy({ selectors: 'h2, h3' });
+ * function ThemeToggle() {
+ *   const { theme, setTheme, resolvedTheme } = useTheme();
  *   return (
- *     <aside>
- *       <TableOfContents activeId={activeId} />
- *     </aside>
+ *     <button onClick={() => setTheme(resolvedTheme === 'dark' ? 'light' : 'dark')}>
+ *       {resolvedTheme === 'dark' ? '☀️' : '🌙'}
+ *     </button>
  *   );
  * }
  * ```
  */
-declare function useScrollSpy({ selectors, ids, rootMargin, threshold, root, enabled, }?: UseScrollSpyOptions): UseScrollSpyReturn;
+declare function useTheme(): {
+    theme: Theme;
+    setTheme: (newTheme: Theme) => void;
+    resolvedTheme: ResolvedTheme;
+};
 
 /** Read the current dark-mode state from the document root. */
 declare function isDarkMode(): boolean;
@@ -125,6 +108,79 @@ declare function usePrefersReducedMotion(): boolean;
  */
 declare function useClickOutside<T extends HTMLElement>(ref: RefObject<T | null> | ReadonlyArray<RefObject<HTMLElement | null>>, callback: () => void, enabled?: boolean): void;
 
+type AnchoredPlacement = 'bottom-start' | 'bottom-end' | 'bottom' | 'top-start' | 'top-end' | 'top' | 'right-start' | 'right-end' | 'right' | 'left-start' | 'left-end' | 'left';
+type AnchoredSide = 'top' | 'bottom' | 'left' | 'right';
+interface UseAnchoredPositionOptions {
+    /** Whether the floating element is currently shown */
+    open: boolean;
+    /** Preferred placement relative to the anchor (flips when out of space) */
+    placement?: AnchoredPlacement;
+    /** Gap between the anchor and the floating element, in px */
+    offset?: number;
+    /** Force the floating element to the anchor's width */
+    matchWidth?: boolean;
+    /** Use the anchor's width as the floating element's minimum width */
+    matchMinWidth?: boolean;
+    /** Minimum distance from the viewport edges, in px */
+    viewportPadding?: number;
+    /** Flip to the opposite vertical side when the preferred side is cramped */
+    allowFlip?: boolean;
+    /** Optional element whose visible rectangle also constrains the popup */
+    boundaryRef?: React.RefObject<HTMLElement | null>;
+    /**
+     * Additional cap on the floating element's height, in px. The height is
+     * always clamped to the available viewport space; this only lowers that
+     * limit further (omitting it does not remove the viewport constraint).
+     */
+    maxHeight?: number;
+}
+interface UseAnchoredPositionReturn<TAnchor extends HTMLElement, TFloating extends HTMLElement> {
+    /** Attach to the element the popup is anchored to (trigger/input) */
+    anchorRef: React.RefObject<TAnchor | null>;
+    /** Attach to the floating element (menu/listbox/panel) */
+    floatingRef: React.RefObject<TFloating | null>;
+    /** Fixed-position style for the floating element — spread onto it */
+    style: React.CSSProperties;
+    /**
+     * Side of the anchor in use after flipping.
+     *
+     * Widened from `'top' | 'bottom'` to {@link AnchoredSide} in 0.8.0 alongside
+     * the new horizontal (`left*` / `right*`) placements — consumers that
+     * annotate this as `'top' | 'bottom'` need to widen their annotation.
+     */
+    actualSide: AnchoredSide;
+    /** Recompute the position (e.g. after async content loads) */
+    update: () => void;
+}
+/**
+ * Positions a floating element (dropdown menu, autocomplete listbox,
+ * date-picker calendar, …) relative to an anchor using `position: fixed`,
+ * so it is never clipped by `overflow: hidden` ancestors.
+ *
+ * Render the floating element through `createPortal(..., document.body)`
+ * and spread the returned `style` onto it. The hook:
+ * - flips vertically when there is not enough space on the preferred side
+ * - clamps horizontally to the viewport or optional boundary element
+ * - constrains `maxHeight` to the available space (add `overflow-auto`)
+ * - tracks scroll, resize, and anchor/content size changes while open
+ *
+ * @example
+ * ```tsx
+ * const { anchorRef, floatingRef, style } = useAnchoredPosition<
+ *   HTMLButtonElement,
+ *   HTMLDivElement
+ * >({ open, placement: 'bottom-start' });
+ *
+ * <button ref={anchorRef} onClick={() => setOpen(!open)}>Open</button>
+ * {open &&
+ *   createPortal(
+ *     <div ref={floatingRef} style={style} className="overflow-auto …">…</div>,
+ *     document.body
+ *   )}
+ * ```
+ */
+declare function useAnchoredPosition<TAnchor extends HTMLElement = HTMLElement, TFloating extends HTMLElement = HTMLElement>({ open, placement, offset, matchWidth, matchMinWidth, viewportPadding, allowFlip, boundaryRef, maxHeight, }: UseAnchoredPositionOptions): UseAnchoredPositionReturn<TAnchor, TFloating>;
+
 /**
  * Hook that triggers a callback when the Escape key is pressed.
  * Useful for closing modals, dropdowns, and other overlays.
@@ -259,6 +315,42 @@ declare function useIsLargeDesktop(): boolean;
 /** Returns true when viewport is smaller than 1024px (mobile/tablet) */
 declare function useIsMobileOrTablet(): boolean;
 
+interface UseScrollSpyOptions {
+    /** CSS selector for the elements to observe (e.g. 'h2, h3, h4') */
+    selectors?: string;
+    /** Explicit list of element IDs to observe (alternative to selectors) */
+    ids?: string[];
+    /** IntersectionObserver root margin (default: '0px 0px -60% 0px') */
+    rootMargin?: string;
+    /** IntersectionObserver threshold (default: 0) */
+    threshold?: number | number[];
+    /** Scroll container element ref. Defaults to document viewport. */
+    root?: RefObject<HTMLElement | null>;
+    /** Whether the hook is active (default: true) */
+    enabled?: boolean;
+}
+interface UseScrollSpyReturn {
+    /** The ID of the currently active (in-view) element */
+    activeId: string | null;
+}
+/**
+ * Tracks which section is currently in the viewport using IntersectionObserver.
+ * Pairs naturally with `TableOfContents` to highlight the active heading.
+ *
+ * @example
+ * ```tsx
+ * function DocsPage() {
+ *   const { activeId } = useScrollSpy({ selectors: 'h2, h3' });
+ *   return (
+ *     <aside>
+ *       <TableOfContents activeId={activeId} />
+ *     </aside>
+ *   );
+ * }
+ * ```
+ */
+declare function useScrollSpy({ selectors, ids, rootMargin, threshold, root, enabled, }?: UseScrollSpyOptions): UseScrollSpyReturn;
+
 /** Insert `draggedId` before/after `targetId` in `ids`. */
 declare function reorderIds(ids: string[], draggedId: string, targetId: string, after: boolean): string[];
 interface UseDragReorderOptions {
@@ -544,4 +636,264 @@ 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 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 };
+/**
+ * Transcript schema for @mieweb/ui media components.
+ *
+ * Provider-agnostic and persistence-agnostic. Canonical time unit is
+ * **milliseconds** (consumers with seconds-based data, e.g. osheet, adapt
+ * at the boundary).
+ *
+ * Shared by TranscriptView, MediaEditor, and useTranscriptEdits.
+ */
+/** Type of transcript word - 'word' for spoken content, 'silence' for detected gaps, 'silence-newline' for longer pauses */
+type WordType = 'word' | 'silence' | 'silence-newline';
+interface TranscriptWord {
+    text: string;
+    startMs: number;
+    endMs: number;
+    /** References Speaker.id when diarization is available */
+    speakerId?: string;
+    confidence?: number;
+    /** Type of word: 'word' for spoken content, 'silence' for detected gaps. Defaults to 'word' */
+    wordType?: WordType;
+}
+/** A diarized segment of contiguous speech (osheet-style granularity) */
+interface TranscriptSegment {
+    text: string;
+    startMs: number;
+    endMs: number;
+    /** References Speaker.id when diarization is available */
+    speakerId?: string;
+    words: TranscriptWord[];
+}
+interface Speaker {
+    id: string;
+    /** Display name (e.g. 'Clinician', 'Patient'). Hosts may remap via speakerLabels props. */
+    name?: string;
+}
+interface Transcript {
+    durationMs: number;
+    speakers?: Speaker[];
+    words: TranscriptWord[];
+    segments?: TranscriptSegment[];
+}
+/**
+ * An editable word that references the original transcript word.
+ * Used in the edited timeline to track deletions and reordering.
+ */
+interface EditableWord {
+    /** Index into the SILENCE-INSERTED baseline timeline (transcript.words
+     *  with detected silence pseudo-words interleaved) — NOT into
+     *  transcript.words. -1 for split/inserted entries with no baseline slot.
+     *  Consumers persisting edits should key by this timeline. */
+    originalIndex: number;
+    /** The word data (from original transcript) */
+    word: TranscriptWord;
+    /** Whether this word is marked as deleted */
+    deleted: boolean;
+    /** Whether this word was inserted (pasted from clipboard) */
+    inserted?: boolean;
+}
+/**
+ * Represents a contiguous segment of playback from the original media.
+ * Used when playing back an edited timeline with potentially reordered/deleted words.
+ */
+interface PlaybackSegment {
+    startMs: number;
+    endMs: number;
+    /** Indices into the editedWords array that this segment covers */
+    editedIndices: number[];
+}
+/** Available playback speed multipliers */
+type PlaybackSpeed = 0.5 | 0.75 | 1 | 1.25 | 1.5 | 1.75 | 2;
+/**
+ * A speed marker applied to a word in the transcript.
+ * The speed applies from this word until the next speed marker or end of transcript.
+ */
+interface SpeedMarker {
+    /** Index in the editedWords array where the speed marker is placed */
+    wordIndex: number;
+    /** The playback speed multiplier */
+    speed: PlaybackSpeed;
+}
+
+/**
+ * useTranscriptEdits — headless transcript-editing state hook.
+ *
+ * Extracted from pulseclip's TranscriptViewer for @mieweb/ui. Holds the
+ * edited word timeline (deletions, insertions, text edits, silence
+ * splitting), a single-level undo stack, an internal clipboard, speed
+ * markers, and derived playback/statistics data.
+ *
+ * Controlled + persistence-agnostic: no DOM, no fetches. Selection lives in
+ * the UI layer — mutations take explicit indices. State flows out via
+ * `onChange` and back in via `initialEditedWords` / `initialUndoStack`.
+ */
+
+/** Default filler words offered for removal */
+declare const DEFAULT_FILLER_WORDS: string[];
+/** Default minimum silence duration in milliseconds to detect and insert */
+declare const DEFAULT_MIN_SILENCE_MS = 400;
+/** Default threshold for "newline" silences - longer pauses that indicate paragraph breaks */
+declare const DEFAULT_NL_SILENCE_MS = 1500;
+/** Clipboard data for cut/copy/paste operations */
+interface TranscriptClipboard {
+    words: EditableWord[];
+    operation: 'cut' | 'copy';
+}
+/** Count and total duration of silences above a given threshold (seconds) */
+interface SilenceThresholdCount {
+    threshold: number;
+    count: number;
+    durationMs: number;
+}
+/**
+ * Builds playback segments from the edited word list.
+ * Consecutive words in original order are merged into single segments.
+ * Inserted (pasted) words each get their own segment since they may be duplicates.
+ */
+declare function buildPlaybackSegments(editedWords: EditableWord[]): PlaybackSegment[];
+/**
+ * Get the effective playback speed at a given word index.
+ * Finds the most recent speed marker at or before the word index,
+ * or returns the default speed if no marker applies.
+ */
+declare function getSpeedAtIndex(wordIndex: number, speedMarkers: SpeedMarker[], defaultSpeed: PlaybackSpeed): PlaybackSpeed;
+/**
+ * Detect silences between words and return a new array with silence pseudo-words inserted.
+ * Silences are detected as gaps between the endMs of one word and startMs of the next.
+ * Silences >= nlSilenceMs are marked as 'silence-newline' for visual line breaks.
+ */
+declare function insertSilences(words: TranscriptWord[], minSilenceMs?: number, nlSilenceMs?: number): TranscriptWord[];
+/** Initialize editable words from transcript, inserting detected silences */
+declare function initEditableWords(transcript: Transcript, minSilenceMs?: number, nlSilenceMs?: number): EditableWord[];
+interface UseTranscriptEditsOptions {
+    /** The source transcript (canonical, immutable) */
+    transcript: Transcript;
+    /** Initial edited words (from saved edits) */
+    initialEditedWords?: EditableWord[];
+    /** Initial undo stack (from saved edits) */
+    initialUndoStack?: EditableWord[][];
+    /** Fired after every mutation (for persistence) */
+    onChange?: (editedWords: EditableWord[], undoStack: EditableWord[][]) => void;
+    /** Minimum silence duration (ms) to detect and insert. Default 400 */
+    minSilenceMs?: number;
+    /** Threshold (ms) for "newline" silences (paragraph breaks). Default 1500 */
+    nlSilenceMs?: number;
+    /** Initial speed markers (from saved edits) */
+    initialSpeedMarkers?: SpeedMarker[];
+    /** Initial default playback speed (from saved edits). Default 1 */
+    initialDefaultSpeed?: PlaybackSpeed;
+}
+interface TranscriptEditStats {
+    /** Non-deleted spoken words (silences excluded) */
+    activeWordCount: number;
+    /** Non-deleted silence entries */
+    activeSilenceCount: number;
+    /** Deleted spoken words */
+    deletedWordCount: number;
+    /** Deleted silence entries */
+    deletedSilenceCount: number;
+    /** Total duration of non-deleted entries, adjusted for speed markers */
+    editedDurationMs: number;
+}
+interface FillerAnalysis {
+    /** Occurrence count per normalized word (fillers and every active word) */
+    matchCounts: Map<string, number>;
+    /** Total duration (ms) per normalized word */
+    durations: Map<string, number>;
+    /** Count + total duration of active silences above each analysis threshold */
+    silenceCounts: SilenceThresholdCount[];
+    /** The built-in filler word list */
+    defaultFillerWords: string[];
+}
+interface UseTranscriptEditsResult {
+    /** The edited timeline (words + silence pseudo-words) */
+    editedWords: EditableWord[];
+    /** Undo snapshots, oldest first */
+    undoStack: EditableWord[][];
+    /** Internal clipboard from the last cut/copy, or null */
+    clipboard: TranscriptClipboard | null;
+    /** Whether any edit has been made (deletions, insertions, text edits, speed markers) */
+    hasEdits: boolean;
+    /** Push the current editedWords onto the undo stack (call before external batch mutations) */
+    pushUndo: () => void;
+    /** Restore the most recent undo snapshot */
+    undo: () => void;
+    /** Step forward again after an undo. Cleared by any new edit. */
+    redo: () => void;
+    /** Whether there is anything to redo */
+    canRedo: boolean;
+    /** Toggle the deleted flag on a single word */
+    toggleWordDeleted: (index: number) => void;
+    /**
+     * Toggle the deleted state of a contiguous range. The first index acts as
+     * the anchor: all words are set to the opposite of the anchor's state
+     * (delete all if anchor active, restore all if anchor deleted).
+     */
+    deleteRange: (indices: number[]) => void;
+    /** Cut words at the given indices into the clipboard (marks them deleted) */
+    cut: (indices: number[]) => void;
+    /** Copy non-deleted words at the given indices into the clipboard */
+    copy: (indices: number[]) => void;
+    /**
+     * Paste the clipboard at a word index. `before` (default true) inserts
+     * before the word at `atIndex`; false inserts after it. Returns the index
+     * where the first pasted word landed, or null if the clipboard was empty.
+     */
+    paste: (atIndex: number, before?: boolean) => number | null;
+    /** Replace a word's text (no-op if unchanged) */
+    setWordText: (index: number, text: string) => void;
+    /** Split a silence at the given index into segments with the given durations (seconds) */
+    splitSilence: (index: number, durationsSec: number[]) => void;
+    /** Toggle the word at the index deleted (editor "delete" action) */
+    deleteWord: (index: number) => void;
+    /** Replace the entire edit state from an external source (e.g. an editable script view); undo-safe */
+    replaceEditedWords: (next: EditableWord[]) => void;
+    /** Mark matching filler words (and silences above the given seconds threshold) deleted */
+    removeFillers: (fillerWords: string[], removeSilenceAboveSec: number | null) => void;
+    /** Rebuild silence detection with new thresholds, preserving word deletions.
+     *  Not undoable — clears the undo stack (prior snapshots reference the old silence layout). */
+    setSilenceThresholds: (minMs: number, nlMs: number) => void;
+    /** Current silence detection thresholds (ms) */
+    silenceThresholds: {
+        minSilenceMs: number;
+        nlSilenceMs: number;
+    };
+    /** Speed markers, sorted by word index */
+    speedMarkers: SpeedMarker[];
+    /** Default playback speed when no marker applies */
+    defaultSpeed: PlaybackSpeed;
+    /** Set the default playback speed (undoable) */
+    setDefaultSpeed: (speed: PlaybackSpeed) => void;
+    /** Add/update/remove a speed marker (re-selecting the same speed removes it; undoable) */
+    toggleSpeedMarker: (index: number, speed: PlaybackSpeed) => void;
+    /** Remove the speed marker at a word index, if any (undoable) */
+    removeSpeedMarker: (index: number) => void;
+    /**
+     * Apply one speed across an index range (typically the selection): marks the
+     * start, restores the prior effective speed after the end. One undo step.
+     */
+    setSpeedForRange: (startIndex: number, endIndex: number, speed: PlaybackSpeed) => void;
+    /** Effective playback speed at a word index */
+    getSpeedAtIndex: (index: number) => PlaybackSpeed;
+    /** The speed marker at a word index, if any */
+    getSpeedMarkerAtIndex: (index: number) => SpeedMarker | undefined;
+    /** Contiguous playback segments built from the edited timeline */
+    playbackSegments: PlaybackSegment[];
+    /** Word/silence counts and speed-adjusted edited duration */
+    stats: TranscriptEditStats;
+    /** Filler word and silence analysis for removal UIs */
+    fillerAnalysis: FillerAnalysis;
+}
+/**
+ * Headless transcript-editing hook. See module docs for scope.
+ *
+ * Undo semantics: each mutation snapshots the full `editedWords` array onto
+ * a single-level stack before applying; `undo` pops one snapshot. Speed
+ * markers and silence-threshold changes are NOT part of the undo stack
+ * (matching the source component).
+ */
+declare function useTranscriptEdits(options: UseTranscriptEditsOptions): UseTranscriptEditsResult;
+
+export { type AnchoredPlacement, DEFAULT_FILLER_WORDS, DEFAULT_MIN_SILENCE_MS, DEFAULT_NL_SILENCE_MS, type Direction, type DragOverState, type FillerAnalysis, type HoverPreviewState, type KeyboardShortcutOptions, type MediaTransportState, RTL_LOCALES, type ResolvedTheme, type SilenceThresholdCount, type Theme, type TranscriptClipboard, type TranscriptEditStats, type UseAnchoredPositionOptions, type UseAnchoredPositionReturn, type UseDragReorderOptions, type UseDragReorderReturn, type UseMediaTransportOptions, type UseMediaTransportReturn, type UseScrollSpyOptions, type UseScrollSpyReturn, type UseStickToBottomOptions, type UseStickToBottomReturn, type UseTranscriptEditsOptions, type UseTranscriptEditsResult, type UseYouTubeHoverPreviewOptions, type UseYouTubeHoverPreviewReturn, buildPlaybackSegments, dragIndicatorClasses, getSpeedAtIndex, initEditableWords, insertSilences, isDarkMode, isRtlLocale, reorderIds, useAnchoredPosition, useClickOutside, useCommandK, useDirection, useDragReorder, useEscapeKey, useFocusTrap, useIsDarkMode, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsMobileOrTablet, useIsSmallTablet, useIsTablet, useKeyboardShortcut, useLiveAnnouncement, useMediaQuery, useMediaTransport, usePrefersReducedMotion, useScrollSpy, useStickToBottom, useStreamEndedBelowFold, useTheme, useTranscriptEdits, useYouTubeHoverPreview };