fancy-ui-react 0.2.0

package/dist/internals/use-anchor-position.js

@@ -0,0 +1,87 @@
+"use client";
+import { useState, useCallback, useRef } from "react";
+import { attachAnchorPosition } from "./anchor-position.js";
+import { useIsomorphicLayoutEffect } from "./dom/ssr.js";
+import { useEventCallback } from "./dom/use-event-callback.js";
+import { useLiveRef } from "./dom/use-live-ref.js";
+function useAnchorPosition(node, options) {
+  const { side = "bottom", align = "center", offset, enabled = true, recomputeKey } = options;
+  const [placement, setPlacement] = useState(() => ({ side, align }));
+  const anchorRef = useLiveRef(options.anchor);
+  const sideRef = useLiveRef(side);
+  const alignRef = useLiveRef(align);
+  const offsetRef = useLiveRef(offset);
+  const recomputeKeyRef = useLiveRef(recomputeKey);
+  const resolveAnchor = useCallback(() => {
+    const anchor = anchorRef.current;
+    if (!anchor) return null;
+    if (typeof anchor === "function") return anchor();
+    if ("current" in anchor) return anchor.current;
+    return anchor;
+  }, [anchorRef]);
+  const onPlacement = useEventCallback(options.onPlacement);
+  const handlePlacement = useCallback(
+    (nextSide, nextAlign) => {
+      setPlacement(
+        (prev) => prev.side === nextSide && prev.align === nextAlign ? prev : { side: nextSide, align: nextAlign }
+      );
+      onPlacement(nextSide, nextAlign);
+    },
+    [onPlacement]
+  );
+  const handleRef = useRef(null);
+  const appliedRef = useRef(null);
+  useIsomorphicLayoutEffect(() => {
+    if (!node || !enabled) return;
+    const handle = attachAnchorPosition(node, {
+      anchor: resolveAnchor,
+      side: sideRef.current,
+      align: alignRef.current,
+      offset: offsetRef.current,
+      onPlacement: handlePlacement
+    });
+    handleRef.current = handle;
+    appliedRef.current = {
+      side: sideRef.current,
+      align: alignRef.current,
+      offset: offsetRef.current,
+      anchor: resolveAnchor(),
+      recomputeKey: recomputeKeyRef.current
+    };
+    return () => {
+      handleRef.current = null;
+      appliedRef.current = null;
+      handle.destroy();
+    };
+  }, [
+    node,
+    enabled,
+    resolveAnchor,
+    handlePlacement,
+    sideRef,
+    alignRef,
+    offsetRef,
+    recomputeKeyRef
+  ]);
+  useIsomorphicLayoutEffect(() => {
+    const handle = handleRef.current;
+    const applied = appliedRef.current;
+    if (!handle || !applied) return;
+    const nextAnchor = resolveAnchor();
+    if (applied.side === side && applied.align === align && applied.offset === offset && applied.anchor === nextAnchor && applied.recomputeKey === recomputeKey) {
+      return;
+    }
+    appliedRef.current = { side, align, offset, anchor: nextAnchor, recomputeKey };
+    handle.update({
+      anchor: resolveAnchor,
+      side,
+      align,
+      offset,
+      onPlacement: handlePlacement
+    });
+  }, [node, side, align, offset, recomputeKey, options.anchor, resolveAnchor, handlePlacement]);
+  return placement;
+}
+export {
+  useAnchorPosition
+};

package/dist/internals/use-autoscroll.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Autoscroll (scroll anchor)
+ *
+ * Keeps a scrollable container pinned to its bottom edge while new content
+ * streams in, and lets go the moment the reader scrolls up to look back.
+ *
+ * "Stuck" is a pure function of the distance from the bottom, recomputed on
+ * every scroll event. There is no programmatic-scroll flag to get out of
+ * sync: whatever the scrollbar says is the truth. It stays a closure
+ * variable in `attachAutoscroll` — never React state — for exactly that
+ * reason.
+ */
+export interface AutoscrollOptions {
+    /** Set to false to release the container and disconnect every listener. */
+    enabled?: boolean;
+    /** How close to the bottom (px) still counts as pinned. */
+    bottomThreshold?: number;
+    /**
+     * Start pinned and jump to the bottom on connect, whatever the
+     * container's scroll position says. For a region that mounts with
+     * content already in it — a reasoning trace joined mid-stream, a
+     * replayed transcript — a fresh container sits at scrollTop 0, which
+     * reads as "the reader scrolled up" and would leave every later chunk
+     * stranded at the top.
+     */
+    pinOnConnect?: boolean;
+    /** Called only when the pinned state flips, never on every scroll. */
+    onStickChange?: (stuck: boolean) => void;
+}
+/** Jump a container to its bottom. Smooth by default. */
+export declare function scrollToBottom(node: HTMLElement, behavior?: ScrollBehavior): void;
+export interface AutoscrollHandle {
+    update(next: AutoscrollOptions): void;
+    destroy(): void;
+}
+export declare function attachAutoscroll(node: HTMLElement, opts?: AutoscrollOptions): AutoscrollHandle;
+/**
+ * Keeps `node` pinned to its bottom edge while content streams in. Mounts
+ * and destroys the core in a layout effect — `pinOnConnect`'s jump writes
+ * `scrollTop`, and a post-paint write is a visible jump — and re-syncs
+ * whenever an option that changes the pinning rules changes.
+ */
+export declare function useAutoscroll(node: HTMLElement | null, options?: AutoscrollOptions): void;

package/dist/internals/use-autoscroll.js

@@ -0,0 +1,128 @@
+"use client";
+import { useRef } from "react";
+import { useEventCallback } from "./dom/use-event-callback.js";
+import { useIsomorphicLayoutEffect } from "./dom/ssr.js";
+const DEFAULT_BOTTOM_THRESHOLD = 40;
+function scrollToBottom(node, behavior = "smooth") {
+  if (typeof node.scrollTo === "function") {
+    node.scrollTo({ top: node.scrollHeight, behavior });
+  } else {
+    node.scrollTop = node.scrollHeight;
+  }
+}
+function attachAutoscroll(node, opts = {}) {
+  let options = opts;
+  let frame = null;
+  let mutations = null;
+  let resizes = null;
+  let connected = false;
+  function isAtBottom() {
+    const threshold = options.bottomThreshold ?? DEFAULT_BOTTOM_THRESHOLD;
+    return node.scrollHeight - node.scrollTop - node.clientHeight <= threshold;
+  }
+  let stuck = isAtBottom();
+  function handleScroll() {
+    const next = isAtBottom();
+    if (next === stuck) return;
+    stuck = next;
+    options.onStickChange?.(next);
+  }
+  function pin() {
+    frame = null;
+    if (!stuck) return;
+    node.scrollTop = node.scrollHeight;
+  }
+  function schedulePin() {
+    if (!stuck || frame !== null) return;
+    frame = requestAnimationFrame(pin);
+  }
+  function observeRows(records) {
+    if (!resizes) return;
+    for (const record of records) {
+      if (record.target !== node) continue;
+      for (const added of record.addedNodes) {
+        if (added instanceof Element) resizes.observe(added);
+      }
+      for (const removed of record.removedNodes) {
+        if (removed instanceof Element) resizes.unobserve(removed);
+      }
+    }
+  }
+  function restick() {
+    if (stuck || !isAtBottom()) return;
+    stuck = true;
+    options.onStickChange?.(true);
+  }
+  function handleMutations(records) {
+    observeRows(records);
+    restick();
+    schedulePin();
+  }
+  function handleResize() {
+    restick();
+    schedulePin();
+  }
+  function connect() {
+    if (connected) return;
+    connected = true;
+    if (options.pinOnConnect) {
+      stuck = true;
+      node.scrollTop = node.scrollHeight;
+    }
+    node.addEventListener("scroll", handleScroll, { passive: true });
+    mutations = new MutationObserver(handleMutations);
+    mutations.observe(node, { childList: true, subtree: true, characterData: true });
+    if (typeof ResizeObserver !== "undefined") {
+      resizes = new ResizeObserver(handleResize);
+      resizes.observe(node);
+      for (const row of node.children) resizes.observe(row);
+    }
+  }
+  function disconnect() {
+    connected = false;
+    node.removeEventListener("scroll", handleScroll);
+    mutations?.disconnect();
+    mutations = null;
+    resizes?.disconnect();
+    resizes = null;
+    if (frame !== null) {
+      cancelAnimationFrame(frame);
+      frame = null;
+    }
+  }
+  if (options.enabled !== false) connect();
+  return {
+    update(next = {}) {
+      const wasConnected = connected;
+      options = next;
+      if (next.enabled === false) {
+        disconnect();
+        return;
+      }
+      connect();
+      if (wasConnected) handleScroll();
+    },
+    destroy: disconnect
+  };
+}
+function useAutoscroll(node, options = {}) {
+  const handleRef = useRef(null);
+  const onStickChange = useEventCallback(options.onStickChange);
+  useIsomorphicLayoutEffect(() => {
+    if (!node) return;
+    const handle = attachAutoscroll(node, { ...options, onStickChange });
+    handleRef.current = handle;
+    return () => {
+      handle.destroy();
+      handleRef.current = null;
+    };
+  }, [node]);
+  useIsomorphicLayoutEffect(() => {
+    handleRef.current?.update({ ...options, onStickChange });
+  }, [node, options.enabled, options.bottomThreshold, onStickChange]);
+}
+export {
+  attachAutoscroll,
+  scrollToBottom,
+  useAutoscroll
+};

package/dist/internals/use-copy.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Copy-to-clipboard state.
+ *
+ * Wraps the async clipboard write in a `copied` flag that falls back to
+ * `false` on its own, so a button can show a transient "Copied!" label
+ * without owning a timer. Nothing is scheduled at construction, and the
+ * clipboard API is only touched inside `copy()`, which keeps `createCopy`
+ * safe to call during a render.
+ */
+export interface CopyState {
+    /** True from a successful copy until `resetMs` has elapsed. */
+    readonly copied: boolean;
+    /** Writes `text` to the clipboard. Resolves false instead of throwing. */
+    copy(text: string): Promise<boolean>;
+    /** Cancels a pending reset. Call from the consumer's teardown. */
+    destroy(): void;
+    /**
+     * Undoes a `destroy()`, so the instance accepts copies again.
+     *
+     * Not part of the Svelte source's surface, and needed for the same
+     * reason `subscribe` is: Svelte runs a teardown exactly once, at the end
+     * of the owner's life, so `destroyed` there is a one-way latch. React
+     * runs the whole mount/teardown/mount rehearsal in development
+     * StrictMode, which latches `destroyed` on an instance that is about to
+     * be used for real — after which `copy()` returns early forever and
+     * `copied` never flips. `useCopy` pairs `arm()` with `destroy()` in one
+     * effect so the rehearsal is a no-op; a pure-factory consumer that calls
+     * `destroy()` once never touches this.
+     */
+    arm(): void;
+    /**
+     * Subscribe to every change of `copied`. Not part of the Svelte source's
+     * surface — the React counterpart of the `$state` rune that made `copied`
+     * reactive there; `useCopy` is what actually reads this.
+     */
+    subscribe(listener: () => void): () => void;
+}
+export declare function createCopy(resetMs?: number): CopyState;
+export interface UseCopyResult {
+    readonly copied: boolean;
+    copy(text: string): Promise<boolean>;
+}
+/**
+ * `copied` flips true on a successful `copy()` and resets after `resetMs`.
+ * Built once per component instance; `destroy()` — the direct analogue of
+ * the source's "call from the consumer's teardown" — runs in the hook's own
+ * cleanup, so it can never be forgotten (D-5).
+ *
+ * The effect arms the instance on the way in and destroys it on the way out,
+ * as one pair. StrictMode's mount/teardown/mount rehearsal therefore leaves
+ * a live, usable instance behind instead of a permanently destroyed one; a
+ * real unmount still ends on `destroy()`, since nothing arms it again.
+ */
+export declare function useCopy(resetMs?: number): UseCopyResult;

package/dist/internals/use-copy.js

@@ -0,0 +1,67 @@
+"use client";
+import { useSyncExternalStore, useEffect } from "react";
+import { useConstant } from "./dom/ssr.js";
+function createCopy(resetMs = 2e3) {
+  let copied = false;
+  let timer;
+  let destroyed = false;
+  let ticket = 0;
+  const listeners = /* @__PURE__ */ new Set();
+  function notify() {
+    for (const listener of listeners) listener();
+  }
+  function clearTimer() {
+    if (timer !== void 0) {
+      clearTimeout(timer);
+      timer = void 0;
+    }
+  }
+  return {
+    get copied() {
+      return copied;
+    },
+    async copy(text) {
+      if (typeof navigator === "undefined" || !navigator.clipboard?.writeText) return false;
+      const mine = ++ticket;
+      try {
+        await navigator.clipboard.writeText(text);
+      } catch {
+        return false;
+      }
+      if (destroyed || mine !== ticket) return true;
+      copied = true;
+      notify();
+      clearTimer();
+      timer = setTimeout(() => {
+        copied = false;
+        timer = void 0;
+        notify();
+      }, resetMs);
+      return true;
+    },
+    destroy() {
+      destroyed = true;
+      clearTimer();
+    },
+    arm() {
+      destroyed = false;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    }
+  };
+}
+function useCopy(resetMs = 2e3) {
+  const state = useConstant(() => createCopy(resetMs));
+  const copied = useSyncExternalStore(state.subscribe, () => state.copied, () => state.copied);
+  useEffect(() => {
+    state.arm();
+    return state.destroy;
+  }, [state]);
+  return { copied, copy: state.copy };
+}
+export {
+  createCopy,
+  useCopy
+};

package/dist/internals/use-elapsed.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Elapsed-time state.
+ *
+ * Every value is derived from the wall clock (`Date.now() - since`) on each
+ * tick rather than accumulated tick by tick, so a throttled background tab
+ * that fires one interval instead of sixty still reports the true elapsed
+ * duration.
+ *
+ * Nothing is scheduled at construction time: timers only exist between
+ * `start()` and `stop()`, which keeps `createElapsed`/`createNow` safe to
+ * build during a render. Consumers start them from an effect — `useElapsed`
+ * and `useNow` do this for you.
+ */
+/**
+ * Format a duration in milliseconds as a compact stopwatch string:
+ * `"0s"`, `"42s"`, `"1m 05s"`, `"1h 03m"`. Negative and non-finite input
+ * collapses to `"0s"`.
+ */
+export declare function formatElapsed(ms: number): string;
+export interface ElapsedOptions {
+    /** Epoch ms the duration is measured from. Defaults to the moment `start()` runs. */
+    since?: number;
+    /** How often the reported value refreshes. Defaults to 1000. */
+    tickMs?: number;
+}
+export interface ElapsedState {
+    readonly ms: number;
+    readonly text: string;
+    readonly running: boolean;
+    /** Start (or restart) ticking. Returns the matching stop function. */
+    start(since?: number): () => void;
+    stop(): void;
+    /**
+     * Subscribe to every change of `ms`/`running`. Not part of the Svelte
+     * source's surface — the React counterpart of the `$state` runes that
+     * made `ms`/`running` reactive there; `useElapsed` is what actually reads
+     * this. Pure factory consumers never need it.
+     */
+    subscribe(listener: () => void): () => void;
+}
+/** Reactive stopwatch: milliseconds since `since`, refreshed every `tickMs`. */
+export declare function createElapsed(opts?: ElapsedOptions): ElapsedState;
+export interface NowState {
+    readonly value: number;
+    /** Start refreshing. Returns the matching stop function. */
+    start(): () => void;
+    stop(): void;
+    /** Subscribe to every refresh. See `ElapsedState.subscribe`. */
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * A single shared "now" that a whole list can read, so a thread of fifty
+ * timestamps costs one interval instead of fifty.
+ */
+export declare function createNow(refreshMs?: number): NowState;
+export interface UseElapsedResult {
+    readonly ms: number;
+    readonly text: string;
+    readonly running: boolean;
+    start(since?: number): () => void;
+    stop(): void;
+}
+/**
+ * Reactive stopwatch. Built once (`ElapsedOptions` is read only at mount,
+ * matching the Svelte source's `createElapsed(opts)` call site — a changed
+ * `tickMs`/`since` prop does not retarget a running timer) and subscribed
+ * through `useSyncExternalStore`; `text` is derived per render from `ms`,
+ * exactly as the source's getter does. Nothing is scheduled by the hook
+ * itself — call the returned `start()` from your own effect or handler,
+ * same as the Svelte side.
+ *
+ * A client-only render reads the live value straight away, exactly as
+ * before; only a hydration render takes the deterministic seed, and the
+ * layout effect below replaces it before the first paint.
+ */
+export declare function useElapsed(options?: ElapsedOptions): UseElapsedResult;
+/**
+ * A shared "now", refreshed every `refreshMs` (30s by default) and reused by
+ * every `useNow` call in the tree — the React-native form of `createNow`'s
+ * whole reason for existing: a thread of fifty timestamps shares one
+ * interval instead of paying for fifty. The refresh cadence is set by
+ * whichever consumer mounts first; a later `useNow` with a different
+ * `refreshMs` shares the interval already running rather than starting a
+ * second one. The interval stops once the last consumer unmounts.
+ *
+ * Before the first consumer anywhere on the page has mounted, the clock has
+ * no value to give and the hook returns `NaN` — the sentinel a server render
+ * and the hydration render that follows it are guaranteed to agree on, and
+ * the one `formatRelativeTime` turns into an empty label rather than a wrong
+ * one. Callers must therefore either pass the value straight to
+ * `formatRelativeTime` (which guards it) or check `Number.isFinite` before
+ * doing arithmetic with it. Every later consumer, including one that mounts
+ * after the clock has been torn down and rebuilt, renders a real timestamp
+ * immediately.
+ */
+export declare function useNow(refreshMs?: number): number;

package/dist/internals/use-elapsed.js

@@ -0,0 +1,195 @@
+"use client";
+import { useSyncExternalStore, useReducer, useEffect } from "react";
+import { useIsomorphicLayoutEffect, useConstant } from "./dom/ssr.js";
+import { useLiveRef } from "./dom/use-live-ref.js";
+const MINUTE = 6e4;
+const HOUR = 36e5;
+function pad(value) {
+  return value < 10 ? `0${value}` : String(value);
+}
+function formatElapsed(ms) {
+  if (!Number.isFinite(ms) || ms <= 0) return "0s";
+  const seconds = Math.floor(ms / 1e3);
+  if (ms < MINUTE) return `${seconds}s`;
+  if (ms < HOUR) return `${Math.floor(ms / MINUTE)}m ${pad(seconds % 60)}s`;
+  return `${Math.floor(ms / HOUR)}h ${pad(Math.floor(ms % HOUR / MINUTE))}m`;
+}
+function createElapsed(opts = {}) {
+  const tickMs = opts.tickMs ?? 1e3;
+  let since = opts.since;
+  let ms = since === void 0 ? 0 : Math.max(0, Date.now() - since);
+  let running = false;
+  let timer;
+  const listeners = /* @__PURE__ */ new Set();
+  function notify() {
+    for (const listener of listeners) listener();
+  }
+  function sync() {
+    ms = Math.max(0, Date.now() - since);
+    notify();
+  }
+  function stop() {
+    if (timer !== void 0) {
+      clearInterval(timer);
+      timer = void 0;
+    }
+    if (running) {
+      running = false;
+      notify();
+    }
+  }
+  function start(nextSince) {
+    stop();
+    since = nextSince ?? since ?? Date.now();
+    sync();
+    running = true;
+    timer = setInterval(sync, tickMs);
+    notify();
+    return stop;
+  }
+  return {
+    get ms() {
+      return ms;
+    },
+    get text() {
+      return formatElapsed(ms);
+    },
+    get running() {
+      return running;
+    },
+    start,
+    stop,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    }
+  };
+}
+function createNow(refreshMs = 3e4) {
+  let value = Date.now();
+  let timer;
+  const listeners = /* @__PURE__ */ new Set();
+  function notify() {
+    for (const listener of listeners) listener();
+  }
+  function stop() {
+    if (timer !== void 0) {
+      clearInterval(timer);
+      timer = void 0;
+    }
+  }
+  function start() {
+    stop();
+    value = Date.now();
+    timer = setInterval(() => {
+      value = Date.now();
+      notify();
+    }, refreshMs);
+    return stop;
+  }
+  return {
+    get value() {
+      return value;
+    },
+    start,
+    stop,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    }
+  };
+}
+function getServerElapsed() {
+  return 0;
+}
+function useElapsed(options = {}) {
+  const elapsed = useConstant(() => createElapsed(options));
+  const ms = useSyncExternalStore(elapsed.subscribe, () => elapsed.ms, getServerElapsed);
+  const running = useSyncExternalStore(
+    elapsed.subscribe,
+    () => elapsed.running,
+    // Deterministic on both sides for a different reason: nothing has
+    // started the stopwatch by the time the first render runs, so the
+    // store's own value is `false` here too.
+    () => false
+  );
+  const rendered = useLiveRef(ms);
+  const [, bump] = useReducer(bumpReducer, 0);
+  useIsomorphicLayoutEffect(() => {
+    if (elapsed.ms !== rendered.current) bump();
+  }, [elapsed, bump]);
+  useEffect(() => elapsed.stop, [elapsed]);
+  return { ms, text: formatElapsed(ms), running, start: elapsed.start, stop: elapsed.stop };
+}
+const sharedClock = (() => {
+  const listeners = /* @__PURE__ */ new Set();
+  let clock = null;
+  let stopClock = null;
+  let retained = 0;
+  let value = Number.NaN;
+  function publish() {
+    if (clock) value = clock.value;
+    for (const listener of listeners) listener();
+  }
+  return {
+    getValue() {
+      return value;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    /**
+     * Keep the interval running for as long as the returned release is
+     * uncalled. Each release is idempotent and belongs to exactly one
+     * retain, so however React interleaves mounts, remounts and
+     * rehearsals, the count cannot drift.
+     */
+    retain(refreshMs) {
+      retained += 1;
+      if (retained === 1) {
+        clock = createNow(refreshMs);
+        clock.subscribe(publish);
+        stopClock = clock.start();
+        publish();
+      }
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        retained -= 1;
+        if (retained === 0) {
+          stopClock?.();
+          stopClock = null;
+          clock = null;
+        }
+      };
+    }
+  };
+})();
+function getServerNow() {
+  return Number.NaN;
+}
+function bumpReducer(n) {
+  return n + 1;
+}
+function useNow(refreshMs = 3e4) {
+  const value = useSyncExternalStore(sharedClock.subscribe, sharedClock.getValue, getServerNow);
+  const rendered = useLiveRef(value);
+  const [, bump] = useReducer(bumpReducer, 0);
+  useIsomorphicLayoutEffect(() => {
+    const release = sharedClock.retain(refreshMs);
+    if (sharedClock.getValue() !== rendered.current) bump();
+    return release;
+  }, [refreshMs, bump]);
+  return value;
+}
+export {
+  createElapsed,
+  createNow,
+  formatElapsed,
+  useElapsed,
+  useNow
+};