@hilum/ui 3.4.0 → 3.5.1

package/src/hooks/use-merge-split.tsx

@@ -0,0 +1,359 @@
+"use client";
+
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { AnimatePresence, motion } from "framer-motion";
+import type { ItemRect } from "./use-proximity-hover";
+
+// Run the layout effect on the client (where it must fire before paint, so a
+// merge/split shows on the first frame) and a no-op-safe useEffect on the server.
+const useIsoLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect;
+
+// Edge spring for the selected-bg merge/split: moderate, no bounce so converging
+// edges meet exactly instead of overshooting. On a merge the inner corners trail
+// by `cornerDelay`, staying rounded until the halves meet.
+const mergeSpring = { type: "spring" as const, duration: 0.16, bounce: 0 };
+const cornerDelay = 0.07;
+// A boundary resolves after its motion finishes (merge → swap to one block;
+// split → drop), driven by a duration timer rather than onAnimationComplete —
+// framer skips that callback when an animation's target equals its current value
+// (which spam-toggling produces), which would otherwise strand a half. The
+// buffer biases late, by which point the halves have met/parted, so it's unseen.
+const convergeMs = (mergeSpring.duration + cornerDelay) * 1000 + 80;
+const splitMs = mergeSpring.duration * 1000 + 80;
+
+// A selected-background block for one render. A run is normally one block; mid
+// merge/split it is drawn as two abutting halves with sharp inner corners.
+type Rect = { top: number; left: number; width: number; height: number };
+export interface SelBlock extends Rect {
+  key: string;
+  radii: [number, number, number, number]; // tl, tr, br, bl
+  instant: boolean; // skip the spring (the zero-shift swap, the split snap-in)
+  exitInstant: boolean; // drop without the fade (absorbed half at the swap)
+  delayCorners: boolean; // trail the corner straightening (merge converge)
+  cornerDelay?: number; // optional per-block delay override
+  opacity?: number; // override the hover-derived opacity (commit ghost = 0)
+  // State a fresh block animates *from* on mount, so it springs into place
+  // instead of snapping when continuity is lost (fast toggling) or the block is
+  // inherently new (a split's lower half). Continuous blocks ignore it.
+  enterFrom?: { top: number; height: number; radii: [number, number, number, number] };
+}
+
+// A contiguous run of selected/checked rows, with a stable id so framer-motion
+// can morph it across renders rather than exit+re-enter.
+export type Run = { start: number; end: number; id: number };
+
+// One in-flight merge or split; geometry is recomputed from the live runs each
+// render so rapid toggles redirect instead of freezing.
+interface Boundary {
+  tid: number;
+  kind: "merge" | "split";
+  survivorId: number; // persisting run (merged run / split's upper run)
+  otherId: number; // merge: absorbed run; split: new lower run
+  gapIndex: number; // bridging/deselected row — where the halves meet
+  phase: "converge" | "commit" | "splitIn" | "diverge";
+}
+
+// Two runs within `outer`, ordered, separated by exactly one row (a single-row
+// bridge — the only shape a click can merge or split).
+function bridgePair(outer: Run, runs: Run[]) {
+  const inside = runs
+    .filter((r) => r.start >= outer.start && r.end <= outer.end)
+    .sort((a, b) => a.start - b.start);
+  if (inside.length !== 2) return null;
+  const [up, lo] = inside;
+  return lo.start === up.end + 2 ? { up, lo, gap: up.end + 1 } : null;
+}
+
+// ── Merge / split boundary animation ─────────────────────────────
+// When one unselected row bridges two selected runs, their inner edges glide to
+// the bridging row's midpoint (facing corners straightening to sharp), then swap
+// to one block with no visible motion — instead of the surviving block
+// spring-growing over the whole union. Deselecting a middle row plays the
+// inverse: snap into two abutting halves, then glide apart.
+//
+// Given the contiguous selection `runs` (with stable ids), the measured
+// `itemRects`, and the corner radius `R` to round to, this returns the list of
+// background blocks to paint — one per run, or two abutting halves for any run
+// currently mid merge/split. Render them with <SelectionBackgrounds>.
+export function useMergeSplitBlocks(runs: Run[], itemRects: ItemRect[], R: number): SelBlock[] {
+  const [boundaries, setBoundaries] = useState<Boundary[]>([]);
+  const prevRunsRef = useRef<Run[]>([]);
+  const tidRef = useRef(0);
+  const timersRef = useRef(new Map<number, ReturnType<typeof setTimeout>>());
+  const runsSig = runs.map((g) => `${g.id}:${g.start}-${g.end}`).join("|");
+
+  // Detect merges/splits before paint (so the first frame already shows the
+  // halves) and drop any boundary the latest selection invalidated (e.g. the
+  // bridge row was toggled again mid-flight).
+  useIsoLayoutEffect(() => {
+    const prev = prevRunsRef.current;
+    const cur = runs;
+    const found: Boundary[] = [];
+    for (const c of cur) {
+      const p = bridgePair(c, prev); // two prev runs collapsed into one
+      if (p && (c.id === p.up.id || c.id === p.lo.id))
+        found.push({
+          tid: ++tidRef.current,
+          kind: "merge",
+          survivorId: c.id,
+          otherId: c.id === p.up.id ? p.lo.id : p.up.id,
+          gapIndex: p.gap,
+          phase: "converge",
+        });
+    }
+    for (const p of prev) {
+      const c = bridgePair(p, cur); // one prev run split into two
+      if (c)
+        found.push({
+          tid: ++tidRef.current,
+          kind: "split",
+          survivorId: c.up.id,
+          otherId: c.lo.id,
+          gapIndex: c.gap,
+          phase: "splitIn",
+        });
+    }
+    prevRunsRef.current = cur.map((r) => ({ ...r }));
+    // Resolve each new boundary after its motion window (merge → swap to one
+    // block; split → drop), so an interrupted animation can't strand a half.
+    for (const b of found) {
+      timersRef.current.set(
+        b.tid,
+        setTimeout(
+          () => {
+            timersRef.current.delete(b.tid);
+            setBoundaries((bs) =>
+              bs.some((x) => x.tid === b.tid)
+                ? bs.flatMap((x) =>
+                    x.tid !== b.tid
+                      ? [x]
+                      : x.kind === "merge"
+                        ? [{ ...x, phase: "commit" as const }]
+                        : [],
+                  )
+                : bs,
+            );
+          },
+          b.kind === "merge" ? convergeMs : splitMs,
+        ),
+      );
+    }
+    setBoundaries((active) => [
+      ...active.filter((b) =>
+        b.kind === "merge"
+          ? cur.some((c) => c.id === b.survivorId && b.gapIndex > c.start && b.gapIndex < c.end)
+          : cur.some((c) => c.id === b.survivorId && c.end === b.gapIndex - 1) &&
+            cur.some((c) => c.id === b.otherId && c.start === b.gapIndex + 1),
+      ),
+      ...found,
+    ]);
+  }, [runsSig]);
+
+  // Clear any pending timers on unmount.
+  useEffect(() => {
+    const timers = timersRef.current;
+    return () => timers.forEach(clearTimeout);
+  }, []);
+
+  // Follow-up render: a fresh split holds its abutting frame once then
+  // diverges; a committed merge is dropped.
+  useEffect(() => {
+    if (!boundaries.some((b) => b.phase === "splitIn" || b.phase === "commit")) return;
+    setBoundaries((bs) =>
+      bs.flatMap((b) =>
+        b.phase === "commit" ? [] : [{ ...b, phase: b.phase === "splitIn" ? "diverge" : b.phase }],
+      ),
+    );
+  }, [boundaries]);
+
+  // Build the blocks to paint: one per run, overridden into abutting halves for
+  // any run in an in-flight boundary.
+  const rectOf = (start: number, end: number): Rect | null => {
+    const s = itemRects[start];
+    const e = itemRects[end];
+    if (!s || !e) return null;
+    return {
+      top: s.top,
+      left: Math.min(s.left, e.left),
+      width: Math.max(s.width, e.width),
+      height: e.top + e.height - s.top,
+    };
+  };
+  const blocks: SelBlock[] = [];
+  for (const run of runs) {
+    const r = rectOf(run.start, run.end);
+    if (r)
+      blocks.push({
+        key: `sel-${run.id}`,
+        ...r,
+        radii: [R, R, R, R],
+        instant: false,
+        exitInstant: false,
+        delayCorners: false,
+      });
+  }
+  const byId = new Map(blocks.map((b) => [b.key, b]));
+  for (const b of boundaries) {
+    const gap = itemRects[b.gapIndex];
+    const sv = byId.get(`sel-${b.survivorId}`);
+    if (!gap || !sv) continue;
+    const midY = gap.top + gap.height / 2;
+    if (b.kind === "merge") {
+      if (b.phase === "commit") {
+        // Zero-shift swap: survivor jumps to the full union (already covered by
+        // its top half + the absorbed bottom half). The absorbed half is held
+        // one render at opacity 0 so removing it next render can't flash a
+        // one-frame overlap with the now-full survivor.
+        sv.instant = true;
+        blocks.push({
+          key: `sel-${b.otherId}`,
+          top: midY,
+          left: sv.left,
+          width: sv.width,
+          height: sv.top + sv.height - midY,
+          radii: [0, 0, R, R],
+          instant: true,
+          exitInstant: true,
+          delayCorners: false,
+          opacity: 0,
+        });
+        continue;
+      }
+      // converge: survivor → top half, absorbed run → bottom-half ghost, inner
+      // corners straightening to sharp.
+      // Slightly trail lower merges while keeping a baseline and small cap.
+      const mergeCornerDelay = Math.min(
+        cornerDelay + 0.03,
+        Math.max(cornerDelay, cornerDelay + (midY / Math.max(gap.height, 1)) * 0.002),
+      );
+      const bottom = sv.top + sv.height;
+      sv.height = midY - sv.top;
+      sv.radii = [R, R, 0, 0];
+      sv.delayCorners = true;
+      sv.cornerDelay = mergeCornerDelay;
+      blocks.push({
+        key: `sel-${b.otherId}`,
+        top: midY,
+        left: sv.left,
+        width: sv.width,
+        height: bottom - midY,
+        radii: [0, 0, R, R],
+        // Mount at full corners so a fresh ghost still animates the
+        // straightening with the same delay as the survivor.
+        enterFrom: { top: midY, height: bottom - midY, radii: [R, R, R, R] },
+        instant: false,
+        exitInstant: true,
+        delayCorners: true,
+        cornerDelay: mergeCornerDelay,
+      });
+    } else if (b.phase === "splitIn") {
+      const lo = byId.get(`sel-${b.otherId}`);
+      if (!lo) continue;
+      // Pin both halves at the seam (identical to the single block); the
+      // diverge render then springs them to their real rects.
+      const bottom = lo.top + lo.height;
+      sv.height = midY - sv.top;
+      sv.radii = [R, R, 0, 0];
+      sv.instant = true;
+      lo.top = midY;
+      lo.height = bottom - midY;
+      lo.radii = [0, 0, R, R];
+      lo.instant = true;
+      lo.enterFrom = { top: midY, height: bottom - midY, radii: [0, 0, R, R] };
+    }
+    // diverge: nothing to override — the steady blocks spring to their real
+    // rects from the seam; the timer drops the boundary.
+  }
+
+  // Split safety net, pinned synchronously. The split boundary above is created
+  // in a layout effect that runs *after* this render, so on the very frame a
+  // split first appears its fresh lower half would mount at its final rect and
+  // snap. Detecting the split here (previous runs vs current) and pinning both
+  // halves at the seam guarantees the lower mounts on the seam regardless of
+  // render/paint timing (the cause of the rapid-toggle snap).
+  for (const p of prevRunsRef.current) {
+    const c = bridgePair(p, runs);
+    const gap = c && itemRects[c.gap];
+    if (!c || !gap) continue;
+    const midY = gap.top + gap.height / 2;
+    const up = byId.get(`sel-${c.up.id}`);
+    const lo = byId.get(`sel-${c.lo.id}`);
+    if (!up || !lo) continue;
+    const bottom = lo.top + lo.height;
+    up.height = midY - up.top;
+    up.radii = [R, R, 0, 0];
+    up.instant = true;
+    lo.top = midY;
+    lo.height = bottom - midY;
+    lo.radii = [0, 0, R, R];
+    lo.instant = true;
+    lo.enterFrom = { top: midY, height: bottom - midY, radii: [0, 0, R, R] };
+  }
+
+  return blocks;
+}
+
+// Renders the selected-background blocks produced by useMergeSplitBlocks — one
+// per run, or two abutting halves mid merge/split. `dimmed` drops the opacity to
+// 0.8 (when the user is hovering a non-selected row) to match the standalone
+// hover indicator; a block's own `opacity` override (e.g. the commit ghost)
+// always wins. Corners are driven numerically so merge/split can straighten and
+// re-round individual corners.
+export function SelectionBackgrounds({ blocks, dimmed }: { blocks: SelBlock[]; dimmed: boolean }) {
+  return (
+    <AnimatePresence>
+      {blocks.map((b) => {
+        const corner = b.delayCorners
+          ? { ...mergeSpring, delay: b.cornerDelay ?? cornerDelay }
+          : mergeSpring;
+        const opacity = b.opacity ?? (dimmed ? 0.8 : 1);
+        return (
+          <motion.div
+            key={b.key}
+            aria-hidden
+            className="absolute bg-active pointer-events-none"
+            initial={
+              b.enterFrom
+                ? {
+                    opacity,
+                    top: b.enterFrom.top,
+                    left: b.left,
+                    width: b.width,
+                    height: b.enterFrom.height,
+                    borderTopLeftRadius: b.enterFrom.radii[0],
+                    borderTopRightRadius: b.enterFrom.radii[1],
+                    borderBottomRightRadius: b.enterFrom.radii[2],
+                    borderBottomLeftRadius: b.enterFrom.radii[3],
+                  }
+                : false
+            }
+            animate={{
+              top: b.top,
+              left: b.left,
+              width: b.width,
+              height: b.height,
+              borderTopLeftRadius: b.radii[0],
+              borderTopRightRadius: b.radii[1],
+              borderBottomRightRadius: b.radii[2],
+              borderBottomLeftRadius: b.radii[3],
+              opacity,
+            }}
+            exit={{ opacity: 0, transition: { duration: b.exitInstant ? 0 : 0.12 } }}
+            transition={
+              b.instant
+                ? { duration: 0 }
+                : {
+                    ...mergeSpring,
+                    borderTopLeftRadius: corner,
+                    borderTopRightRadius: corner,
+                    borderBottomRightRadius: corner,
+                    borderBottomLeftRadius: corner,
+                    opacity: { duration: 0.08 },
+                  }
+            }
+          />
+        );
+      })}
+    </AnimatePresence>
+  );
+}

package/src/hooks/use-proximity-hover.ts

@@ -0,0 +1,208 @@
+"use client";
+
+import {
+  useRef,
+  useState,
+  useCallback,
+  useEffect,
+  type Dispatch,
+  type RefObject,
+  type SetStateAction,
+} from "react";
+
+export interface ItemRect {
+  top: number;
+  height: number;
+  left: number;
+  width: number;
+}
+
+interface UseProximityHoverOptions {
+  axis?: "x" | "y";
+}
+
+interface UseProximityHoverReturn {
+  activeIndex: number | null;
+  setActiveIndex: Dispatch<SetStateAction<number | null>>;
+  itemRects: ItemRect[];
+  sessionRef: RefObject<number>;
+  handlers: {
+    onMouseMove: (e: React.MouseEvent) => void;
+    onMouseEnter: () => void;
+    onMouseLeave: () => void;
+  };
+  registerItem: (index: number, element: HTMLElement | null) => void;
+  measureItems: () => void;
+}
+
+export function useProximityHover<T extends HTMLElement>(
+  containerRef: RefObject<T | null>,
+  options: UseProximityHoverOptions = {},
+): UseProximityHoverReturn {
+  const { axis = "y" } = options;
+  const itemsRef = useRef(new Map<number, HTMLElement>());
+  const [activeIndex, setActiveIndex] = useState<number | null>(null);
+  const [itemRects, setItemRects] = useState<ItemRect[]>([]);
+  const itemRectsRef = useRef<ItemRect[]>([]);
+  const sessionRef = useRef(0);
+  const rafIdRef = useRef<number | null>(null);
+  const remeasureRafIdRef = useRef<number | null>(null);
+
+  const measureItems = useCallback(() => {
+    const container = containerRef.current;
+    if (!container) return;
+    const rects: ItemRect[] = [];
+    itemsRef.current.forEach((element, index) => {
+      // Use offset* instead of getBoundingClientRect so measurements are
+      // unaffected by CSS transforms (e.g. scaleY animation on the parent
+      // motion.div). offsetTop/offsetLeft are layout values relative to the
+      // offsetParent (the scroll container), matching the coordinate space
+      // used by `position: absolute` children.
+      rects[index] = {
+        top: element.offsetTop,
+        height: element.offsetHeight,
+        left: element.offsetLeft,
+        width: element.offsetWidth,
+      };
+    });
+    itemRectsRef.current = rects;
+    setItemRects(rects);
+  }, [containerRef]);
+
+  const registerItem = useCallback(
+    (index: number, element: HTMLElement | null) => {
+      if (element) {
+        itemsRef.current.set(index, element);
+      } else {
+        itemsRef.current.delete(index);
+      }
+      // Coalesce rapid register/unregister calls (e.g. when an AnimatePresence
+      // remounts a list of rows) into a single remeasure on the next frame,
+      // so consumers don't have to manually call measureItems after the
+      // container's children swap.
+      if (remeasureRafIdRef.current !== null) {
+        cancelAnimationFrame(remeasureRafIdRef.current);
+      }
+      remeasureRafIdRef.current = requestAnimationFrame(() => {
+        remeasureRafIdRef.current = null;
+        measureItems();
+      });
+    },
+    [measureItems],
+  );
+
+  const handleMouseMove = useCallback(
+    (e: React.MouseEvent) => {
+      const mouseX = e.clientX;
+      const mouseY = e.clientY;
+
+      if (rafIdRef.current !== null) {
+        cancelAnimationFrame(rafIdRef.current);
+      }
+
+      rafIdRef.current = requestAnimationFrame(() => {
+        rafIdRef.current = null;
+        const container = containerRef.current;
+        if (!container) return;
+
+        const containerRect = container.getBoundingClientRect();
+        const mousePos = axis === "x" ? mouseX : mouseY;
+
+        let closestIndex: number | null = null;
+        let closestDistance = Infinity;
+        let containingIndex: number | null = null;
+
+        const rects = itemRectsRef.current;
+        // Convert content-relative rects to viewport coords using live scroll
+        const scrollOffset = axis === "x" ? container.scrollLeft : container.scrollTop;
+        const borderOffset = axis === "x" ? container.clientLeft : container.clientTop;
+        const containerEdge = axis === "x" ? containerRect.left : containerRect.top;
+        // Item rects are layout values (offset*); the container's bounding rect
+        // reflects any cumulative ancestor transform: scale. Compute the scale
+        // factor so we can map layout coords into the same visual viewport
+        // space the mouse cursor lives in.
+        const layoutSize = axis === "x" ? container.offsetWidth : container.offsetHeight;
+        const visualSize = axis === "x" ? containerRect.width : containerRect.height;
+        const scale = layoutSize > 0 ? visualSize / layoutSize : 1;
+
+        for (let index = 0; index < rects.length; index++) {
+          const r = rects[index];
+          if (!r) continue;
+
+          const contentPos = axis === "x" ? r.left : r.top;
+          const itemStart = containerEdge + (borderOffset + contentPos - scrollOffset) * scale;
+          const itemSize = (axis === "x" ? r.width : r.height) * scale;
+          const itemEnd = itemStart + itemSize;
+
+          if (mousePos >= itemStart && mousePos <= itemEnd) {
+            containingIndex = index;
+          }
+
+          const itemCenter = itemStart + itemSize / 2;
+          const distance = Math.abs(mousePos - itemCenter);
+
+          if (distance < closestDistance) {
+            closestDistance = distance;
+            closestIndex = index;
+          }
+        }
+
+        setActiveIndex(containingIndex ?? closestIndex);
+      });
+    },
+    [axis, containerRef],
+  );
+
+  const handleMouseEnter = useCallback(() => {
+    sessionRef.current += 1;
+  }, []);
+
+  const handleMouseLeave = useCallback(() => {
+    if (rafIdRef.current !== null) {
+      cancelAnimationFrame(rafIdRef.current);
+      rafIdRef.current = null;
+    }
+    setActiveIndex(null);
+  }, []);
+
+  // Clean up rAF on unmount
+  useEffect(() => {
+    return () => {
+      if (rafIdRef.current !== null) {
+        cancelAnimationFrame(rafIdRef.current);
+      }
+      if (remeasureRafIdRef.current !== null) {
+        cancelAnimationFrame(remeasureRafIdRef.current);
+      }
+    };
+  }, []);
+
+  return {
+    activeIndex,
+    setActiveIndex,
+    itemRects,
+    sessionRef,
+    handlers: {
+      onMouseMove: handleMouseMove,
+      onMouseEnter: handleMouseEnter,
+      onMouseLeave: handleMouseLeave,
+    },
+    registerItem,
+    measureItems,
+  };
+}
+
+/**
+ * Hook for child items to register themselves with the proximity hover system.
+ * Call in useEffect with the item's ref and index.
+ */
+export function useRegisterProximityItem(
+  registerItem: (index: number, element: HTMLElement | null) => void,
+  index: number,
+  ref: RefObject<HTMLElement | null>,
+) {
+  useEffect(() => {
+    registerItem(index, ref.current);
+    return () => registerItem(index, null);
+  }, [index, registerItem, ref]);
+}

package/src/index.ts

@@ -16,6 +16,7 @@ export * from "./components/activity-feed";
 export * from "./components/alert-dialog";
 export * from "./components/alert";
 export * from "./components/aspect-ratio";
+export * from "./components/ask-user-questions";
 export * from "./components/avatar-stack";
 export * from "./components/avatar";
 export * from "./components/badge";
@@ -28,7 +29,9 @@ export * from "./components/card-heading";
 export * from "./components/card";
 export * from "./components/carousel";
 export * from "./components/chart";
+export * from "./components/chat-message";
 export * from "./components/checkbox";
+export * from "./components/checkbox-group";
 export * from "./components/collapsible";
 export * from "./components/color-input";
 export * from "./components/color-picker";
@@ -42,14 +45,18 @@ export * from "./components/date-picker";
 export * from "./components/description-list";
 export * from "./components/dialog";
 export * from "./components/drawer";
+export * from "./components/dropdown";
 export * from "./components/dropdown-menu";
 export * from "./components/empty-state";
 export * from "./components/field";
+export * from "./components/file-thumbnail";
 export * from "./components/file-dropzone";
 export * from "./components/grid-list";
 export * from "./components/help-tooltip";
 export * from "./components/hover-card";
+export * from "./components/input-copy";
 export * from "./components/input-group";
+export * from "./components/input-message";
 export * from "./components/input-number";
 export * from "./components/input-otp";
 export * from "./components/input";
@@ -57,8 +64,12 @@ export * from "./components/kbd";
 export * from "./components/label";
 export * from "./components/media-asset-card";
 export * from "./components/media-object";
+export * from "./components/menu-item";
 export * from "./components/menubar";
+export * from "./components/mobile-drawer";
 export * from "./components/native-select";
+export * from "./components/nav-item";
+export * from "./components/nav-menu";
 export * from "./components/navigation-menu";
 export * from "./components/notification";
 export * from "./components/page-heading";
@@ -88,7 +99,10 @@ export * from "./components/steps";
 export * from "./components/switch";
 export * from "./components/table";
 export * from "./components/tabs";
+export * from "./components/tabs-subtle";
 export * from "./components/textarea";
+export * from "./components/thinking-indicator";
+export * from "./components/thinking-steps";
 export * from "./components/titled-card";
 export * from "./components/toggle-group";
 export * from "./components/toggle";

package/src/lib/elevated.tsx

@@ -0,0 +1,52 @@
+"use client";
+
+import { forwardRef, type ComponentPropsWithoutRef, type ReactNode } from "react";
+import { cn } from "./utils";
+import { useSurface, SurfaceProvider } from "./surface-context";
+import { surfaceClasses } from "./surface-classes";
+
+interface ElevatedProps extends ComponentPropsWithoutRef<"div"> {
+  /**
+   * Steps above the current substrate.
+   *
+   * The component's own surface level becomes `min(substrate + offset, 8)`
+   * and is re-provided to descendants via SurfaceProvider, so further
+   * nesting walks up the ladder automatically.
+   *
+   * Conventional offsets:
+   *   2 — dropdown / popover / select menu
+   *   4 — dialog / modal
+   */
+  offset: number;
+  /**
+   * Override for the shadow level. Defaults to the computed surface level.
+   *
+   * Pass a fixed value when the component should keep a constant shadow
+   * weight regardless of how deeply it's nested — e.g. a dropdown always
+   * reads `shadow-surface-3` whether it opens on the page or inside a
+   * dialog, even though its background tracks the substrate.
+   */
+  shadowLevel?: number;
+  children?: ReactNode;
+}
+
+const Elevated = forwardRef<HTMLDivElement, ElevatedProps>(
+  ({ offset, shadowLevel, className, children, ...props }, ref) => {
+    const substrate = useSurface();
+    const level = Math.min(substrate + offset, 8);
+    return (
+      <SurfaceProvider value={level}>
+        <div
+          ref={ref}
+          className={cn(surfaceClasses(level, shadowLevel ?? level), className)}
+          {...props}
+        >
+          {children}
+        </div>
+      </SurfaceProvider>
+    );
+  },
+);
+Elevated.displayName = "Elevated";
+
+export { Elevated };