@vvedantb/ui 0.17.0 → 0.18.0

package/src/utils/cat-color.ts

@@ -0,0 +1,123 @@
+/**
+ * Muted categorical ramp for hash-assigned identity colour — session tab
+ * groups, repo tiles, avatars. Not for status; status uses `status-*`.
+ *
+ * The ramp is eight CSS vars (`--cat-1` … `--cat-8`, see globals.css),
+ * exposed as the Tailwind `cat` colour family. This module owns the
+ * id → slot hashing once, so every consumer picks the same slot for the
+ * same id and the class names stay literal (Tailwind's extractor cannot
+ * see `` `bg-cat-${n}` ``, only the strings written out below).
+ */
+
+/** Number of slots in the muted categorical ramp (--cat-1 … --cat-8). */
+export const CAT_SLOT_COUNT = 8;
+
+export type CatSlot = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+
+export interface CatColorClasses {
+  /** Solid foreground colour — text, icons, and `currentColor` accents. */
+  text: string;
+  /** Solid fill — underline strips, dots, anything with no text on top. */
+  bg: string;
+  /** Tinted fill, sized to sit behind `text` at readable contrast in both themes. */
+  bgTint: string;
+  /** Solid border stroke. */
+  border: string;
+}
+
+// One literal record per slot so Tailwind's class extractor sees every
+// `cat-N` utility it needs to generate — a template string would hide them.
+const CAT_COLOR_CLASSES: Record<CatSlot, CatColorClasses> = {
+  1: {
+    text: "text-cat-1",
+    bg: "bg-cat-1",
+    bgTint: "bg-cat-1/12",
+    border: "border-cat-1",
+  },
+  2: {
+    text: "text-cat-2",
+    bg: "bg-cat-2",
+    bgTint: "bg-cat-2/12",
+    border: "border-cat-2",
+  },
+  3: {
+    text: "text-cat-3",
+    bg: "bg-cat-3",
+    bgTint: "bg-cat-3/12",
+    border: "border-cat-3",
+  },
+  4: {
+    text: "text-cat-4",
+    bg: "bg-cat-4",
+    bgTint: "bg-cat-4/12",
+    border: "border-cat-4",
+  },
+  5: {
+    text: "text-cat-5",
+    bg: "bg-cat-5",
+    bgTint: "bg-cat-5/12",
+    border: "border-cat-5",
+  },
+  6: {
+    text: "text-cat-6",
+    bg: "bg-cat-6",
+    bgTint: "bg-cat-6/12",
+    border: "border-cat-6",
+  },
+  7: {
+    text: "text-cat-7",
+    bg: "bg-cat-7",
+    bgTint: "bg-cat-7/12",
+    border: "border-cat-7",
+  },
+  8: {
+    text: "text-cat-8",
+    bg: "bg-cat-8",
+    bgTint: "bg-cat-8/12",
+    border: "border-cat-8",
+  },
+};
+
+// Maps the hash's 0–7 bucket onto the 1–8 slot type without a cast — indexing
+// a `Record<number, CatSlot>` by the modulo result stays inside the type
+// system, unlike `(index + 1) as CatSlot`.
+const SLOT_BY_INDEX: Record<number, CatSlot> = {
+  0: 1,
+  1: 2,
+  2: 3,
+  3: 4,
+  4: 5,
+  5: 6,
+  6: 7,
+  7: 8,
+};
+
+function slotFromIndex(index: number): CatSlot {
+  return SLOT_BY_INDEX[index] ?? 1;
+}
+
+/**
+ * Stable, order-independent slot for an arbitrary id.
+ *
+ * Same rolling hash the old tab-group palette used (`hash * 31 + charCode`),
+ * reused here rather than invented fresh so ids that landed in the same
+ * bucket before still land in the same bucket now.
+ */
+export function catSlotForId(id: string): CatSlot {
+  let hash = 0;
+  for (let i = 0; i < id.length; i++) {
+    hash = (hash * 31 + id.charCodeAt(i)) | 0;
+  }
+  const index = Math.abs(hash) % CAT_SLOT_COUNT;
+  return slotFromIndex(index);
+}
+
+/** Class set for a known slot — for consumers that need to remap a legacy bucket onto a slot. */
+export function catColorForSlot(slot: CatSlot): CatColorClasses {
+  return CAT_COLOR_CLASSES[slot];
+}
+
+/** Pre-composed class set for an arbitrary id. */
+export function catColorForId(id: string): CatColorClasses {
+  return catColorForSlot(catSlotForId(id));
+}

package/src/utils/dayjs.ts

@@ -0,0 +1,6 @@
+import dayjs from "dayjs";
+import relativeTime from "dayjs/plugin/relativeTime";
+
+dayjs.extend(relativeTime);
+
+export default dayjs;

package/src/utils/gesture.ts

@@ -0,0 +1,59 @@
+/**
+ * Gesture physics from Apple's *Designing Fluid Interfaces* (WWDC 2018).
+ *
+ * These two functions are the whole of it, and both were previously copied
+ * verbatim into each surface that needed them. They are pure maths with no
+ * React or DOM dependency — import them, do not re-derive them.
+ */
+
+/**
+ * Progressive resistance past a boundary. A hard stop reads as frozen; damping
+ * that grows with the overshoot reads as "responsive, but there is nothing more
+ * here". Returns the *damped* overshoot, so callers add it back to the bound:
+ *
+ * ```ts
+ * width < MIN ? MIN - rubberband(MIN - width, MIN) : width
+ * ```
+ *
+ * @param overshoot How far past the bound the pointer is, always positive.
+ * @param dimension The span the resistance is measured against — normally the
+ *   bound itself, or the container size for a percentage-based drag.
+ */
+export function rubberband(
+  overshoot: number,
+  dimension: number,
+  constant = 0.55,
+): number {
+  return (
+    (overshoot * dimension * constant) /
+    (dimension + constant * Math.abs(overshoot))
+  );
+}
+
+/**
+ * Where a flick would come to rest, so a gesture can be animated to where it
+ * was *going* rather than to the nearest snap point from where it was released.
+ * Add the result to the current position, then pick the snap target nearest
+ * that projection.
+ *
+ * This is the exponential-decay form Apple ships, not the textbook
+ * `v² / (2·decel)` — they are not the same curve.
+ *
+ * @param initialVelocity Release velocity in px/s.
+ * @param decelerationRate 0.998 matches normal scroll feel; 0.99 is snappier.
+ */
+export function projectVelocity(
+  initialVelocity: number,
+  decelerationRate = 0.998,
+): number {
+  return (
+    ((initialVelocity / 1000) * decelerationRate) / (1 - decelerationRate)
+  );
+}
+
+/**
+ * Movement in px before a drag commits to a direction. Arming on the first
+ * pixel turns sloppy clicks into drags; a hold-to-arm delay makes a fast,
+ * decisive drag fail outright. Distance-based activation avoids both.
+ */
+export const DRAG_ACTIVATION_DISTANCE_PX = 8;

package/src/utils/runtimeVisibility.ts

@@ -0,0 +1,167 @@
+"use client";
+
+import { useCallback, useEffect, useRef } from "react";
+
+/**
+ * Page-visibility and on-screen budget for infinite animations.
+ *
+ * CSS animations pause via `html[data-page-hidden]` / `[data-anim-offscreen]`
+ * / parked `[aria-hidden="true"]` hosts in the host stylesheet. WAAPI
+ * (Spinner, LoadingState) has no CSS play-state hook, so
+ * {@link bindRuntimeAnimation} pauses those directly.
+ *
+ * Decorative animation chrome (`data-anim-chrome` on BorderBeam's overlay,
+ * Shimmer's copy, LoadingState's grid) is itself `aria-hidden` so AT skips
+ * it. That must not count as "the user cannot see this" — #764 paused every
+ * composer beam and session-row Drive grid by matching those hosts.
+ *
+ * Pausing is visually identical while the user is looking: playback resumes
+ * from the same offset when the tab or element is shown again.
+ */
+
+/** Parked subtree (cached session shell, minimized Ave). Skips decorative chrome. */
+const ARIA_HIDDEN_SUBTREE = '[aria-hidden="true"]:not([data-anim-chrome])';
+
+type IntersectionListener = (intersecting: boolean) => void;
+
+const intersectionListeners = new WeakMap<Element, Set<IntersectionListener>>();
+let sharedObserver: IntersectionObserver | null = null;
+let pageVisibilityStarted = false;
+let ariaHiddenWatchStarted = false;
+const animationSyncs = new Set<() => void>();
+
+function pageIsHidden(): boolean {
+  return (
+    typeof document !== "undefined" && document.visibilityState === "hidden"
+  );
+}
+
+function elementOrAncestorHidden(el: Element): boolean {
+  return el.closest(ARIA_HIDDEN_SUBTREE) !== null;
+}
+
+function flushAnimationSyncs(): void {
+  for (const sync of animationSyncs) sync();
+}
+
+function ensureAriaHiddenWatch(): void {
+  if (ariaHiddenWatchStarted || typeof MutationObserver === "undefined") return;
+  if (typeof document === "undefined") return;
+  ariaHiddenWatchStarted = true;
+  const observer = new MutationObserver(flushAnimationSyncs);
+  observer.observe(document.documentElement, {
+    subtree: true,
+    attributes: true,
+    attributeFilter: ["aria-hidden"],
+  });
+}
+
+function getSharedObserver(): IntersectionObserver | null {
+  if (typeof IntersectionObserver === "undefined") return null;
+  if (sharedObserver) return sharedObserver;
+  sharedObserver = new IntersectionObserver(
+    (entries) => {
+      for (const entry of entries) {
+        if (entry.isIntersecting) {
+          entry.target.removeAttribute("data-anim-offscreen");
+        } else {
+          entry.target.setAttribute("data-anim-offscreen", "");
+        }
+        const listeners = intersectionListeners.get(entry.target);
+        if (!listeners) continue;
+        for (const listener of listeners) listener(entry.isIntersecting);
+      }
+    },
+    // Keep a small lead so a scroll into view does not show a frozen frame.
+    { rootMargin: "64px", threshold: 0 },
+  );
+  return sharedObserver;
+}
+
+/** Sets `html[data-page-hidden]` so CSS can pause compositor animations. */
+export function ensureRuntimeVisibility(): void {
+  if (pageVisibilityStarted || typeof document === "undefined") return;
+  pageVisibilityStarted = true;
+  const sync = () => {
+    document.documentElement.toggleAttribute("data-page-hidden", pageIsHidden());
+  };
+  sync();
+  document.addEventListener("visibilitychange", () => {
+    sync();
+    flushAnimationSyncs();
+  });
+}
+
+/**
+ * Marks `el` with `data-anim-offscreen` when it leaves the viewport and
+ * optionally notifies. Shared observer — many cells/spinners cost one IO.
+ */
+export function observeAnimVisibility(
+  el: Element,
+  onChange?: IntersectionListener,
+): () => void {
+  ensureRuntimeVisibility();
+  const observer = getSharedObserver();
+  if (!observer) return () => {};
+  let listeners = intersectionListeners.get(el);
+  if (!listeners) {
+    listeners = new Set();
+    intersectionListeners.set(el, listeners);
+    observer.observe(el);
+  }
+  if (onChange) listeners.add(onChange);
+  return () => {
+    if (onChange) listeners?.delete(onChange);
+    if (listeners && listeners.size === 0) {
+      observer.unobserve(el);
+      intersectionListeners.delete(el);
+      el.removeAttribute("data-anim-offscreen");
+    }
+  };
+}
+
+/** Callback ref that applies {@link observeAnimVisibility} to the node. */
+export function useAnimOffscreenRef<T extends Element>(): (
+  node: T | null,
+) => void {
+  const cleanupRef = useRef<(() => void) | null>(null);
+  const setRef = useCallback((node: T | null) => {
+    cleanupRef.current?.();
+    cleanupRef.current = node ? observeAnimVisibility(node) : null;
+  }, []);
+  useEffect(() => () => cleanupRef.current?.(), []);
+  return setRef;
+}
+
+/**
+ * Play a WAAPI loop only while the page is visible and `el` is on screen.
+ * Returns a detach cleanup that also cancels the animation.
+ */
+export function bindRuntimeAnimation(
+  el: Element,
+  animation: Animation,
+): () => void {
+  ensureRuntimeVisibility();
+  let intersecting = true;
+  const sync = () => {
+    const hidden =
+      pageIsHidden() || !intersecting || elementOrAncestorHidden(el);
+    if (hidden) {
+      if (animation.playState === "running") animation.pause();
+      return;
+    }
+    if (animation.playState === "paused") animation.play();
+  };
+  const unobserve = observeAnimVisibility(el, (next) => {
+    intersecting = next;
+    sync();
+  });
+  ensureAriaHiddenWatch();
+  animationSyncs.add(sync);
+  sync();
+  return () => {
+    animationSyncs.delete(sync);
+    unobserve();
+    animation.cancel();
+  };
+}

package/src/utils/sharedClock.ts

@@ -0,0 +1,96 @@
+/**
+ * One timeout chain per interval, shared by every subscriber.
+ *
+ * Sidebar rows used to each own a `useQuantizedNow` timer; elapsed labels
+ * each owned a 1s interval. The snapshot is still `floor(now / interval)`,
+ * so the displayed value is unchanged — only the wake-ups collapse.
+ *
+ * The chain pauses while `document.hidden`: nothing on screen needs a tick,
+ * and becoming visible notifies immediately so labels catch up in one paint.
+ */
+
+export type QuantizedStore = {
+  listeners: Set<() => void>;
+  timer: ReturnType<typeof setTimeout> | undefined;
+  visHandler: (() => void) | undefined;
+};
+
+const stores = new Map<number, QuantizedStore>();
+
+export function quantizedSnapshot(intervalMs: number, now = Date.now()): number {
+  return Math.floor(now / intervalMs) * intervalMs;
+}
+
+export function msUntilNextBoundary(
+  intervalMs: number,
+  now = Date.now(),
+): number {
+  const remainder = now % intervalMs;
+  return remainder === 0 ? intervalMs : intervalMs - remainder;
+}
+
+function pageHidden(): boolean {
+  return (
+    typeof document !== "undefined" && document.visibilityState === "hidden"
+  );
+}
+
+function disarmTimer(store: QuantizedStore): void {
+  if (store.timer === undefined) return;
+  clearTimeout(store.timer);
+  store.timer = undefined;
+}
+
+function arm(store: QuantizedStore, intervalMs: number): void {
+  disarmTimer(store);
+  if (pageHidden() || store.listeners.size === 0) return;
+  store.timer = setTimeout(() => {
+    for (const listener of store.listeners) listener();
+    arm(store, intervalMs);
+  }, msUntilNextBoundary(intervalMs));
+}
+
+export function subscribeQuantized(
+  intervalMs: number,
+  onChange: () => void,
+): () => void {
+  let store = stores.get(intervalMs);
+  if (!store) {
+    store = { listeners: new Set(), timer: undefined, visHandler: undefined };
+    stores.set(intervalMs, store);
+  }
+  store.listeners.add(onChange);
+  if (store.listeners.size === 1) {
+    arm(store, intervalMs);
+    if (typeof document !== "undefined") {
+      store.visHandler = () => {
+        if (pageHidden()) {
+          disarmTimer(store);
+          return;
+        }
+        for (const listener of store.listeners) listener();
+        arm(store, intervalMs);
+      };
+      document.addEventListener("visibilitychange", store.visHandler);
+    }
+  }
+  return () => {
+    store.listeners.delete(onChange);
+    if (store.listeners.size > 0) return;
+    disarmTimer(store);
+    if (store.visHandler && typeof document !== "undefined") {
+      document.removeEventListener("visibilitychange", store.visHandler);
+    }
+    stores.delete(intervalMs);
+  };
+}
+
+/** Test seam — how many listeners share `intervalMs`. */
+export function quantizedListenerCount(intervalMs: number): number {
+  return stores.get(intervalMs)?.listeners.size ?? 0;
+}
+
+/** Test seam — whether a timer is armed for `intervalMs`. */
+export function quantizedTimerArmed(intervalMs: number): boolean {
+  return stores.get(intervalMs)?.timer !== undefined;
+}

package/src/utils/surface-radius.ts

@@ -0,0 +1,16 @@
+/**
+ * Radius classes for theme-aware corners (`tokens.css` or the compat file).
+ *
+ * - Compact single-line rows that should stay pills on a "full" radius theme:
+ *   `rounded-lg` (maps to `var(--radius)`).
+ * - Menu and nav rows: `rounded-menu-item` (capped).
+ * - Controls: `rounded-control` (capped).
+ * - Wide or multi-line surfaces (modals, dropdown panels, cards):
+ *   `rounded-surface` (clamped) so they do not become ovals.
+ */
+
+/** Cards, dialogs, dropdown panels, kanban columns, alerts, calendars. */
+export const SURFACE_RADIUS_CLASS = "rounded-surface";
+
+/** Inputs, textareas, selects, input groups. */
+export const CONTROL_RADIUS_CLASS = "rounded-control";

package/src/utils/useDragSensors.ts

@@ -0,0 +1,58 @@
+import {
+  KeyboardSensor,
+  MouseSensor,
+  TouchSensor,
+  useSensor,
+  useSensors,
+  type SensorDescriptor,
+  type SensorOptions,
+} from "@dnd-kit/core";
+import { sortableKeyboardCoordinates } from "@dnd-kit/sortable";
+import { DRAG_ACTIVATION_DISTANCE_PX } from "./gesture";
+
+/** How long a finger must rest before a drag arms, in ms. */
+const TOUCH_HOLD_MS = 200;
+
+/** How far a finger may stray during the hold without cancelling it, in px. */
+const TOUCH_HOLD_TOLERANCE_PX = 10;
+
+/**
+ * The house dnd-kit activation split, for every draggable surface.
+ *
+ * A single `PointerSensor` cannot serve both input types. Mouse arms on
+ * **distance**, because dnd-kit's `delay` constraint cancels activation outright
+ * when the pointer travels past `tolerance` before the timer fires — so a fast,
+ * decisive drag never picks the item up at all. Touch keeps a **hold**, because
+ * distance-based activation there competes with the scroll the finger is also
+ * describing, and the browser wins: the pointer is cancelled and the drag dies.
+ *
+ * Keyboard is included so a drag is reachable without a pointer.
+ *
+ * Pass `{ sortable: true }` inside a `SortableContext`. `sortableKeyboardCoordinates`
+ * translates arrow keys into the *next item's* position rather than a raw pixel
+ * offset, which is the difference between a keyboard reorder that lands on a row
+ * and one that nudges the item a few pixels into nothing. The flag lives here
+ * rather than being a `coordinateGetter` each call site imports, because that is
+ * exactly what two call sites silently dropped when they adopted this hook. It is
+ * opt-in because the getter reads `active.data.current.sortable` and returns
+ * nothing without it, so defaulting it on would take keyboard dragging away from
+ * the non-sortable surfaces (the gantt bars).
+ */
+export function useDragSensors({
+  sortable = false,
+}: { sortable?: boolean } = {}): SensorDescriptor<SensorOptions>[] {
+  return useSensors(
+    useSensor(MouseSensor, {
+      activationConstraint: { distance: DRAG_ACTIVATION_DISTANCE_PX },
+    }),
+    useSensor(TouchSensor, {
+      activationConstraint: {
+        delay: TOUCH_HOLD_MS,
+        tolerance: TOUCH_HOLD_TOLERANCE_PX,
+      },
+    }),
+    useSensor(KeyboardSensor, {
+      coordinateGetter: sortable ? sortableKeyboardCoordinates : undefined,
+    }),
+  );
+}