@vvedantb/ui 0.32.0 → 0.34.0

package/README.md

@@ -212,7 +212,10 @@ import { SessionsHoverCard } from "@vvedantb/ui";
 ## Panels, search and confirm
 
 ```tsx
-import { ConfirmDialog, SearchInput, SlideOverPanel } from "@vvedantb/ui";
+import {
+  ConfirmDialog, Drawer, DrawerContent, DrawerTitle, SearchInput, Sheet, SheetContent,
+  SheetTitle, SlideOverPanel,
+} from "@vvedantb/ui";
 
 <div className="relative">
   <SlideOverPanel open={open} onClose={() => setOpen(false)} header={<h2>Details</h2>}>
@@ -220,6 +223,20 @@ import { ConfirmDialog, SearchInput, SlideOverPanel } from "@vvedantb/ui";
   </SlideOverPanel>
 </div>
 
+<Sheet open={open} onOpenChange={setOpen} direction="right">
+  <SheetContent motionBlur surfaceClassName="p-4">
+    <SheetTitle>Details</SheetTitle>
+    Body
+  </SheetContent>
+</Sheet>
+
+{/* Drawer* names are aliases of Sheet* */}
+<Drawer open={open} onOpenChange={setOpen}>
+  <DrawerContent motionBlur>
+    <DrawerTitle>Share</DrawerTitle>
+  </DrawerContent>
+</Drawer>
+
 <SearchInput value={query} onChange={setQuery} label="Search files" shortcut="/" />
 
 <SearchInput variant="toolbar" value={query} onChange={setQuery} />
@@ -229,7 +246,8 @@ import { ConfirmDialog, SearchInput, SlideOverPanel } from "@vvedantb/ui";
 <ConfirmDialog size="md" open={open} onOpenChange={setOpen} title="Delete item?" description="This cannot be undone." confirmLabel="Delete" variant="destructive" onConfirm={remove} />
 ```
 
-- `SlideOverPanel`: a right-side panel, absolutely positioned inside its nearest positioned parent. It is not a portal or dialog. It slides in with a spring and is hidden below `md`. Only the close button closes it (no Escape, no outside click). `width` is `"w-96"` (default) or `"w-80"`. `closeLabel` defaults to `"Close panel"`. `className` merges last.
+- `Sheet` / `Drawer` (vaul): mobile sheet and side drawer. `SheetContent` / `DrawerContent` take `side` (defaults to the root `direction`), opt-in `motionBlur` (default `false`) and `surfaceClassName`. With `motionBlur`, `@web-kits/motion-blur` blurs the panel only while it slides or is dragged (Echo, 180° shutter; off under `prefers-reduced-motion`). The moving element stays transparent; an inner `data-slot="sheet-surface"` holds the fill, shadow, corners and scroll. `className` then styles the moving host; `surfaceClassName` styles the surface. Without `motionBlur`, the DOM matches the previous single-element surface (`surfaceClassName` merges onto it after `className`). `Drawer*` exports are aliases of the `Sheet*` parts.
+- `SlideOverPanel`: a right-side panel, absolutely positioned inside its nearest positioned parent. It is not a portal or dialog. It slides in with a spring and is hidden below `md`. Only the close button closes it (no Escape, no outside click). `width` is `"w-96"` (default) or `"w-80"`. `closeLabel` defaults to `"Close panel"`. `className` merges last. Does not use `motionBlur`.
 - `SearchInput`: the search field. A `ClearInput` with a search icon on the left and the clear button on the right (shown while there is text; clearing calls `onChange("")`). `label` (default `"Search"`) is the `aria-label` and, without `placeholder`, the placeholder. `clearLabel` defaults to `"Clear search"`. `shortcut` (such as `"/"` or `"⌘K"`) shows a `Kbd` hint on the right while the value is empty. `size`: `"sm"` (`h-8`, default) or `"md"` (`h-10`). `variant`: `"default"` or `"toolbar"` (transparent until hover or focus, `rounded-field`, full width on mobile and `sm:w-44 md:w-52`). Other input props pass through; `enterKeyHint="search"`. `className` goes to the `<input>`, `wrapperClassName` to the wrapper, the ref to the `<input>`.
 - `ToolbarSearchInput` (deprecated in 0.17.0): a wrapper over `<SearchInput variant="toolbar">` with `placeholder="Search..."`. `className` goes to the wrapper, `inputClassName` to the `<input>`.
 - Field focus: every field (`Input`, `Textarea`, `Select` and `RadixSelect` triggers, `ClearInput`, `SearchInput`, `InputGroup`, date and time picker triggers) uses `fieldFocusClass`: the border turns `focus-border` and a 1px `ring-focus-ring` shows. Wrappers use `fieldFocusWithinClass` (`has-focus-visible:`). Both are exported for app fields.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvedantb/ui",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "license": "MIT",
   "description": "Shared React 19 UI for web apps: one main JavaScript entry (primitives, shell pieces, app helpers including the Convex and Clerk provider, VITE env parsing and ensure-user, artifact viewers over the @vvedantb/server artifacts core, native tokens), a client entry without @vvedantb/server, convex or Clerk for Chrome extensions, design-token CSS, shared Tailwind v4 CSS, a Tailwind preset and packaged Instrument Sans fonts.",
   "type": "module",
@@ -89,6 +89,7 @@
     "@dnd-kit/modifiers": "^9.0.0",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
+    "@web-kits/motion-blur": "^0.1.0",
     "dayjs": "^1.11.13",
     "katex": "^0.16.45",
     "media-chrome": "^4.14.0",

package/src/ui/sheet.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import * as React from "react";
+import { useMotionBlur } from "@web-kits/motion-blur/react";
 import { Drawer as DrawerPrimitive } from "vaul";
 import { cn } from "../utils/cn";
 import { assignRef } from "../utils/ref";
@@ -58,34 +59,132 @@ const SheetOverlay = React.forwardRef<
 ));
 SheetOverlay.displayName = "SheetOverlay";
 
-const sheetSideClass: Record<SheetSide, string> = {
+// Position and size. Stays on the element vaul moves.
+const sheetSideLayoutClass: Record<SheetSide, string> = {
   bottom:
-    "inset-x-0 bottom-[var(--overlay-vv-bottom,0px)] mt-24 flex max-h-[min(96dvh,calc(var(--overlay-vv-height,100dvh)-1.5rem))] h-auto flex-col rounded-t-2xl pb-[max(0.75rem,env(safe-area-inset-bottom,0px))]",
-  top: "inset-x-0 top-0 mb-24 flex h-auto max-h-[var(--overlay-vv-height,100dvh)] flex-col rounded-b-2xl pt-[max(0.75rem,env(safe-area-inset-top,0px))]",
-  left: "inset-y-2 left-2 right-auto flex h-auto w-80 max-w-[88vw] flex-col rounded-2xl",
-  right:
-    "inset-y-2 left-auto right-2 flex h-auto w-80 max-w-[88vw] flex-col rounded-2xl",
+    "inset-x-0 bottom-[var(--overlay-vv-bottom,0px)] mt-24 flex max-h-[min(96dvh,calc(var(--overlay-vv-height,100dvh)-1.5rem))] h-auto flex-col",
+  top: "inset-x-0 top-0 mb-24 flex h-auto max-h-[var(--overlay-vv-height,100dvh)] flex-col",
+  left: "inset-y-2 left-2 right-auto flex h-auto w-80 max-w-[88vw] flex-col",
+  right: "inset-y-2 left-auto right-2 flex h-auto w-80 max-w-[88vw] flex-col",
 };
 
+// Corners and safe-area padding. Go on the visible surface.
+const sheetSideSurfaceClass: Record<SheetSide, string> = {
+  bottom: "rounded-t-2xl pb-[max(0.75rem,env(safe-area-inset-bottom,0px))]",
+  top: "rounded-b-2xl pt-[max(0.75rem,env(safe-area-inset-top,0px))]",
+  left: "rounded-2xl",
+  right: "rounded-2xl",
+};
+
+// Without `motionBlur`, one element is both the moving part and the surface.
+const sheetContentClass =
+  "fixed z-50 overflow-y-auto bg-overlay/95 text-overlay-foreground smooth-shadow-ring-xl outline-hidden backdrop-blur-xl motion-reduce:transition-none";
+
+// With `motionBlur`, the element vaul moves has to stay transparent, because the
+// blur is drawn into its first child. It also stops clipping (no overflow), so
+// the streak and the surface shadow can reach past its edges. `after:hidden`
+// drops vaul's `::after` fill: it inherits the now transparent background, and
+// the old `overflow-y-auto` clipped it anyway.
+const sheetBlurHostClass =
+  "fixed z-50 outline-hidden motion-reduce:transition-none after:hidden";
+
+// The visible surface inside it. It fills the host and is the scroll container.
+const sheetBlurSurfaceClass =
+  "flex min-h-0 flex-auto flex-col overflow-y-auto bg-overlay/95 text-overlay-foreground smooth-shadow-ring-xl backdrop-blur-xl";
+
+/**
+ * `@web-kits/motion-blur` reads transforms with `DOMMatrix` and the computed
+ * `translate`, polls `getAnimations()` and checks `matchMedia`, and throws
+ * without them. jsdom, happy-dom and browsers without the individual transform
+ * properties lack some of these, so the blur stays off there and the sheet
+ * still renders.
+ */
+function supportsMotionBlur(node: HTMLElement): boolean {
+  return (
+    typeof DOMMatrix === "function" &&
+    typeof window.matchMedia === "function" &&
+    typeof node.getAnimations === "function" &&
+    typeof window.getComputedStyle(node).translate === "string"
+  );
+}
+
+const syncedEchoCopies = new WeakSet<Element>();
+
+/**
+ * Echo draws copies of the surface next to it, and a fresh copy starts at
+ * scroll 0. Give each copy the surface's scroll once, so a scrolled sheet does
+ * not flash its top while it closes.
+ */
+function syncEchoScroll(host: HTMLElement): void {
+  const surface = host.firstElementChild;
+  if (!(surface instanceof HTMLElement)) return;
+  for (let copy = surface.nextElementSibling; copy; copy = copy.nextElementSibling) {
+    if (syncedEchoCopies.has(copy) || copy.getAttribute("aria-hidden") !== "true") continue;
+    syncedEchoCopies.add(copy);
+    copy.scrollTop = surface.scrollTop;
+    copy.scrollLeft = surface.scrollLeft;
+  }
+}
+
 const SheetContent = React.forwardRef<
   React.ComponentRef<typeof DrawerPrimitive.Content>,
   React.ComponentPropsWithoutRef<typeof DrawerPrimitive.Content> & {
     /** Defaults to the parent Sheet's `direction`. */
     side?: SheetSide;
+    /**
+     * Blur the sheet while it slides in, out or is dragged, with
+     * `@web-kits/motion-blur` (Echo, 180° shutter). Off under
+     * `prefers-reduced-motion`. When `true`, the content element moves and
+     * stays transparent, and an inner `data-slot="sheet-surface"` div holds the
+     * fill, shadow, corners and scroll. `className` then styles the moving
+     * element only (size, position); use `surfaceClassName` for the surface.
+     * Default `false`.
+     */
+    motionBlur?: boolean;
+    /**
+     * Classes for the visible surface: the inner div when `motionBlur` is on,
+     * otherwise the content element itself (after `className`).
+     */
+    surfaceClassName?: string;
   }
->(({ className, children, side: sideProp, ...props }, ref) => {
+>(({ className, children, side: sideProp, motionBlur = false, surfaceClassName, ...props }, ref) => {
   const direction = React.useContext(SheetDirectionContext);
   const side = sideProp ?? direction;
   const overlayCleanupRef = React.useRef<(() => void) | null>(null);
+  const blurCleanupRef = React.useRef<(() => void) | null>(null);
+  const hostRef = React.useRef<HTMLDivElement | null>(null);
+
+  const onBlurFrame = React.useCallback(() => {
+    if (hostRef.current) syncEchoScroll(hostRef.current);
+  }, []);
+  // Called on every render (hook rules); it does nothing until its ref is set.
+  const { ref: attachMotionBlur } = useMotionBlur({ onFrame: onBlurFrame });
+
+  const detachMotionBlur = React.useCallback(() => {
+    blurCleanupRef.current?.();
+    blurCleanupRef.current = null;
+  }, []);
+
+  const connectMotionBlur = React.useCallback(
+    (node: HTMLDivElement) => {
+      detachMotionBlur();
+      if (!supportsMotionBlur(node)) return;
+      blurCleanupRef.current = attachMotionBlur(node) ?? null;
+    },
+    [attachMotionBlur, detachMotionBlur],
+  );
 
   const mergedRef = React.useCallback(
     (node: HTMLDivElement | null) => {
       overlayCleanupRef.current?.();
       overlayCleanupRef.current = null;
+      detachMotionBlur();
+      hostRef.current = node;
       if (node) {
         const viewport = connectOverlayViewport(node);
         const keyboard = connectKeyboardScroll(node);
         const pointerEvents = connectBodyPointerEventsFix();
+        if (motionBlur) connectMotionBlur(node);
         overlayCleanupRef.current = () => {
           viewport();
           keyboard();
@@ -94,34 +193,65 @@ const SheetContent = React.forwardRef<
       }
       assignRef(ref, node);
     },
-    [ref],
+    [ref, motionBlur, connectMotionBlur, detachMotionBlur],
   );
 
   React.useLayoutEffect(() => {
     return () => {
       overlayCleanupRef.current?.();
       overlayCleanupRef.current = null;
+      detachMotionBlur();
     };
-  }, []);
+  }, [detachMotionBlur]);
+
+  // vaul may keep the same content node when only `motionBlur` flips, so the
+  // callback ref above does not always re-run. Sync attach/detach here.
+  React.useLayoutEffect(() => {
+    const node = hostRef.current;
+    if (!node) return;
+    if (motionBlur) connectMotionBlur(node);
+    else detachMotionBlur();
+  }, [motionBlur, connectMotionBlur, detachMotionBlur]);
+
+  const handle =
+    side === "bottom" || side === "top" ? (
+      <div className="flex min-h-11 shrink-0 items-center justify-center">
+        <SheetHandle className="relative mx-auto h-1 w-12 shrink-0 rounded-full bg-surface-tertiary after:absolute after:inset-x-[-16px] after:inset-y-[-20px] after:content-['']" />
+      </div>
+    ) : null;
 
   return (
     <SheetPortal>
       <SheetOverlay />
       <DrawerPrimitive.Content
         ref={mergedRef}
-        className={cn(
-          "fixed z-50 overflow-y-auto bg-overlay/95 text-overlay-foreground smooth-shadow-ring-xl outline-hidden backdrop-blur-xl motion-reduce:transition-none",
-          sheetSideClass[side],
-          className,
-        )}
+        className={
+          motionBlur
+            ? cn(sheetBlurHostClass, sheetSideLayoutClass[side], className)
+            : cn(
+                sheetContentClass,
+                sheetSideLayoutClass[side],
+                sheetSideSurfaceClass[side],
+                className,
+                surfaceClassName,
+              )
+        }
         {...props}
       >
-        {side === "bottom" || side === "top" ? (
-          <div className="flex min-h-11 shrink-0 items-center justify-center">
-            <SheetHandle className="relative mx-auto h-1 w-12 shrink-0 rounded-full bg-surface-tertiary after:absolute after:inset-x-[-16px] after:inset-y-[-20px] after:content-['']" />
+        {motionBlur ? (
+          <div
+            data-slot="sheet-surface"
+            className={cn(sheetBlurSurfaceClass, sheetSideSurfaceClass[side], surfaceClassName)}
+          >
+            {handle}
+            {children}
           </div>
-        ) : null}
-        {children}
+        ) : (
+          <>
+            {handle}
+            {children}
+          </>
+        )}
       </DrawerPrimitive.Content>
     </SheetPortal>
   );
@@ -165,3 +295,19 @@ export {
   SheetHeader,
   SheetFooter,
 };
+
+// The same parts under vaul's name, for apps that call the sliding panel a
+// drawer. One implementation, so `DrawerContent` takes `motionBlur` too.
+export {
+  Sheet as Drawer,
+  SheetPortal as DrawerPortal,
+  SheetOverlay as DrawerOverlay,
+  SheetTrigger as DrawerTrigger,
+  SheetClose as DrawerClose,
+  SheetContent as DrawerContent,
+  SheetHandle as DrawerHandle,
+  SheetTitle as DrawerTitle,
+  SheetDescription as DrawerDescription,
+  SheetHeader as DrawerHeader,
+  SheetFooter as DrawerFooter,
+};

package/tokens/README.md

@@ -13,7 +13,7 @@ Design tokens and shared Tailwind v4 CSS for the vvedantb web apps. The CSS and
 | `@vvedantb/ui/tokens/css/modal.css` | `src/css/modal.css` | `.t-modal`, `.is-open`, `.is-closing` and `t-modal-presence-wait` (`@layer components`). |
 | `@vvedantb/ui/tokens/css/tabs.css` | `src/css/tabs.css` | `.t-tabs` container (0.15.0), `.t-tab` with its press scale, active colour, `.t-tabs-pill`, small-screen `.t-tabs` scrolling. |
 | `@vvedantb/ui/tokens/css/tabs-pills.css` | `src/css/tabs-pills.css` | `--tabs-*` colour variables, `.t-tabs--segmented`, `.t-tabs--pills` and pill hover / active fills. |
-| `@vvedantb/ui/tokens/css/utilities.css` | `src/css/utilities.css` | `@utility hit-target` and `@utility reveal-on-hover`. `rounded-surface` moved to `tokens.css` in 0.7.1. |
+| `@vvedantb/ui/tokens/css/utilities.css` | `src/css/utilities.css` | `@utility hit-target`, `reveal-on-hover`, `motion-press`, `motion-base`, `motion-emphasized` and `scrollbar-none`. The motion utilities read `--motion-fast`, `--motion-base`, `--motion-ease-out` and `--motion-ease-emphasized`, with defaults in the utility. `rounded-surface` moved to `tokens.css` in 0.7.1. |
 | `@vvedantb/ui/tokens/css/scrollbar-thin.css` | `src/css/scrollbar-thin.css` | `.scrollbar-thin` (`@layer utilities`, always emitted). Imported by `tokens.css` from 0.15.0. |
 | `@vvedantb/ui/tokens/css/clear-input.css` | `src/css/clear-input.css` | `ClearInput` layers (`.t-clear*`) and the `--clear-*` / `--glow-*` timings. Imported by `tokens.css`. From 0.15.1 the layers clip in `.t-clear-clip`, so `.t-clear` keeps the focus ring, and the placeholder layer only shows during `.is-clearing`. |
 | `@vvedantb/ui/tokens/css/motion.css` | `src/css/motion.css` | `.ui-page-enter`, `.ui-enter`, `.ui-enter-up`, `.ui-stagger`, their keyframes and reduced-motion rules, and the `html[data-page-motion="off"]` overrides for `PageMotionProvider`. Imported by `tokens.css`. |
@@ -72,7 +72,7 @@ Tailwind inlines an `@import` where it sits, even in the middle of a file (it mu
 | `modal.css` | `--modal-open-dur`, `--modal-close-dur`, `--modal-scale`, `--modal-scale-close`, `--modal-ease` | tokens.css (0.15.0), or app `:root` with the compat file |
 | `tabs.css` | `--tabs-dur`, `--tabs-ease` (tokens.css, or app `:root` with the compat file); `--tabs-text-muted`, `--tabs-text-active`, `--tabs-pill-bg` | colours: tabs-pills.css or the app theme |
 | `tabs-pills.css` | `--muted`, `--segment`, `--segment-foreground`, `--default` | tokens.css or the app theme |
-| `utilities.css` | `--breakpoint-sm` (Tailwind default or app theme) | Tailwind |
+| `utilities.css` | `--breakpoint-sm` (Tailwind default or app theme); optional `--motion-*` | Tailwind |
 | `scrollbar-thin.css` | `--scrollbar` | tokens.css or the app theme |
 | `clear-input.css`, `motion.css` | none (own `:root` defaults) | |
 | `type-scale.css` | none (own `@theme` values) | |

package/tokens/src/css/compat-shadcn-rgb.css

@@ -81,6 +81,16 @@
   border-radius: clamp(0.75rem, var(--radius), 1rem);
 }
 
+@utility rounded-t-surface {
+  border-radius: clamp(0.75rem, var(--radius), 1rem)
+    clamp(0.75rem, var(--radius), 1rem) 0 0;
+}
+
+@utility rounded-b-surface {
+  border-radius: 0 0 clamp(0.75rem, var(--radius), 1rem)
+    clamp(0.75rem, var(--radius), 1rem);
+}
+
 @utility rounded-menu-item {
   border-radius: min(var(--radius), 0.5rem);
 }

package/tokens/src/css/utilities.css

@@ -1,6 +1,13 @@
 /*
  * @vvedantb/ui/tokens/css/utilities.css: Tailwind `@utility` helpers. Generated
  * only when used, and they take variants (e.g. `max-sm:hit-target`).
+ *
+ * The motion utilities read these variables. Set them on :root to change
+ * (defaults shown):
+ *   --motion-fast: 150ms (press feedback)
+ *   --motion-base: 220ms (colour, shadow, opacity)
+ *   --motion-ease-out: cubic-bezier(0.22, 1, 0.36, 1)
+ *   --motion-ease-emphasized: cubic-bezier(0.2, 0.8, 0.2, 1)
  */
 
 /* Extends sub-40px controls to a 40x40px tap target without changing layout.
@@ -32,3 +39,52 @@
     }
   }
 }
+
+/* Each motion utility lists `scale`, `translate` and `rotate` as well as
+   `transform`. Tailwind v4 compiles `scale-[0.98]` to `scale: 0.98` and
+   `translate-x-*` to `translate: ...`, the individual transform properties.
+   `transition-property: transform` does not match them, so without them a
+   press or slide would not animate. */
+
+/* Hover and state changes: colour, shadow, opacity and transforms. */
+@utility motion-base {
+  transition-property:
+    color, background-color, border-color, box-shadow, transform, scale,
+    translate, rotate, opacity;
+  transition-duration: var(--motion-base, 220ms);
+  transition-timing-function: var(--motion-ease-out, cubic-bezier(0.22, 1, 0.36, 1));
+}
+
+/* Movement on screen: transforms, opacity and shadow on the emphasized curve. */
+@utility motion-emphasized {
+  transition-property: transform, scale, translate, rotate, opacity, box-shadow;
+  transition-duration: var(--motion-base, 220ms);
+  transition-timing-function: var(--motion-ease-emphasized, cubic-bezier(0.2, 0.8, 0.2, 1));
+}
+
+/* Pressable controls: pair with `active:scale-[0.97]`. The press runs on
+   --motion-fast and colour trails on --motion-base. It covers colour too,
+   because Tailwind's `transition-colors` comes later in the sheet at the same
+   specificity and would replace this whole declaration. So call sites need no
+   separate `transition-*` class. */
+@utility motion-press {
+  transition-property:
+    transform, scale, translate, rotate, color, background-color, border-color,
+    box-shadow, opacity, fill, stroke;
+  transition-duration:
+    var(--motion-fast, 150ms), var(--motion-fast, 150ms),
+    var(--motion-fast, 150ms), var(--motion-fast, 150ms),
+    var(--motion-base, 220ms), var(--motion-base, 220ms),
+    var(--motion-base, 220ms), var(--motion-base, 220ms),
+    var(--motion-base, 220ms), var(--motion-base, 220ms),
+    var(--motion-base, 220ms);
+  transition-timing-function: var(--motion-ease-out, cubic-bezier(0.22, 1, 0.36, 1));
+}
+
+/* Hides the scrollbar. The element still scrolls (wheel, drag, script). */
+@utility scrollbar-none {
+  scrollbar-width: none;
+  &::-webkit-scrollbar {
+    display: none;
+  }
+}

package/tokens/src/tokens.css

@@ -118,6 +118,16 @@
   border-radius: clamp(0.75rem, var(--radius), 1rem);
 }
 
+@utility rounded-t-surface {
+  border-radius: clamp(0.75rem, var(--radius), 1rem)
+    clamp(0.75rem, var(--radius), 1rem) 0 0;
+}
+
+@utility rounded-b-surface {
+  border-radius: 0 0 clamp(0.75rem, var(--radius), 1rem)
+    clamp(0.75rem, var(--radius), 1rem);
+}
+
 @utility rounded-menu-item {
   border-radius: min(var(--radius), 0.5rem);
 }