@vvedantb/ui 0.31.1 → 0.33.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.31.1",
+  "version": "0.33.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",
@@ -35,6 +35,7 @@
     "./tokens/css/border-beam.css": "./tokens/src/css/border-beam.css",
     "./tokens/css/markdown.css": "./tokens/src/css/markdown.css",
     "./tokens/css/marquee.css": "./tokens/src/css/marquee.css",
+    "./tokens/css/type-scale.css": "./tokens/src/css/type-scale.css",
     "./tokens/compat/shadcn-rgb.css": "./tokens/src/css/compat-shadcn-rgb.css",
     "./tokens/css/*.css": "./tokens/src/css/*.css",
     "./tokens/tailwind-preset": {
@@ -88,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

@@ -17,6 +17,7 @@ Design tokens and shared Tailwind v4 CSS for the vvedantb web apps. The CSS and
 | `@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`. |
+| `@vvedantb/ui/tokens/css/type-scale.css` | `src/css/type-scale.css` | The `text-*` scale (`3xs` 10px to `7xl` 72px, with `2xs` 11px and `2sm` 13px) as `@theme` variables. Each tier has its own line height and letter-spacing: positive below 14px (`+0.01em` at 10-11px), `0` at `sm`, negative above (`-0.03em` at `7xl`). Imported by `tokens.css`. |
 | `@vvedantb/ui/tokens/css/animations.css` | `src/css/animations.css` | `animate-aurora`, `animate-fade-in-up`, `animate-indeterminate` as `@theme` (CSS-first apps). |
 | `@vvedantb/ui/tokens/css/compat-shadcn-rgb.css`, `@vvedantb/ui/tokens/compat/shadcn-rgb.css` | `src/css/compat-shadcn-rgb.css` | Replaces `tokens.css` for apps with shadcn-style `R G B` channel variables. Defines only the UI-only `--color-*` names as `rgb(var(--x) / alpha)` references, `--radius-field`, `--scrollbar`, `--field-radius` (both `min(var(--radius), 0.625rem)` from 0.16.3), the same three radius utilities as `tokens.css` and `.glass-panel-strong` (solid `--popover` from 0.15.0). Import it **or** `tokens.css`, never both. |
 | `@vvedantb/ui/tokens/css/index.css` | `src/css/index.css` | base + dialog + modal + tabs + tabs-pills + utilities + animations + nav-icons, for new CSS-first apps (`tokens.css` brings scrollbar-thin). |
@@ -74,6 +75,7 @@ Tailwind inlines an `@import` where it sits, even in the middle of a file (it mu
 | `utilities.css` | `--breakpoint-sm` (Tailwind default or app theme) | 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) | |
 | `animations.css` | none | |
 | `tailwind-preset` | the CSS variables named in its colour map, `--radius`, `--field-radius` | tokens.css or the app theme |
 

package/tokens/src/css/type-scale.css

@@ -0,0 +1,61 @@
+/*
+ * @vvedantb/ui/tokens/css/type-scale.css: the `text-*` scale with size-specific
+ * tracking. tokens.css imports it. Apps that pick files one by one can import
+ * it alone, after tailwindcss.
+ *
+ * Tracking is never one value for all sizes. Small UI text gets positive
+ * letter-spacing to stay legible. Display text gets negative letter-spacing,
+ * because letters look further apart as they grow. Line heights are the
+ * Tailwind defaults, so only tracking changes for the standard tiers.
+ *
+ * `3xs` (10px), `2xs` (11px) and `2sm` (13px) fill the gaps below `text-base`,
+ * so call sites do not need arbitrary `text-[11px]` classes.
+ *
+ * An explicit `tracking-*` or `leading-*` utility still wins. To change a tier,
+ * set its variable in the app's own `@theme` block.
+ */
+
+@theme {
+  --text-3xs: 0.625rem;
+  --text-3xs--line-height: 0.875rem;
+  --text-3xs--letter-spacing: 0.01em;
+  --text-2xs: 0.6875rem;
+  --text-2xs--line-height: 1rem;
+  --text-2xs--letter-spacing: 0.01em;
+  --text-xs: 0.75rem;
+  --text-xs--line-height: 1rem;
+  --text-xs--letter-spacing: 0.005em;
+  --text-2sm: 0.8125rem;
+  --text-2sm--line-height: 1.125rem;
+  --text-2sm--letter-spacing: 0.005em;
+  --text-sm: 0.875rem;
+  --text-sm--line-height: 1.25rem;
+  --text-sm--letter-spacing: 0em;
+  --text-base: 1rem;
+  --text-base--line-height: 1.5rem;
+  --text-base--letter-spacing: -0.006em;
+  --text-lg: 1.125rem;
+  --text-lg--line-height: 1.75rem;
+  --text-lg--letter-spacing: -0.01em;
+  --text-xl: 1.25rem;
+  --text-xl--line-height: 1.75rem;
+  --text-xl--letter-spacing: -0.012em;
+  --text-2xl: 1.5rem;
+  --text-2xl--line-height: 2rem;
+  --text-2xl--letter-spacing: -0.015em;
+  --text-3xl: 1.875rem;
+  --text-3xl--line-height: 2.25rem;
+  --text-3xl--letter-spacing: -0.018em;
+  --text-4xl: 2.25rem;
+  --text-4xl--line-height: 2.5rem;
+  --text-4xl--letter-spacing: -0.022em;
+  --text-5xl: 3rem;
+  --text-5xl--line-height: 1;
+  --text-5xl--letter-spacing: -0.025em;
+  --text-6xl: 3.75rem;
+  --text-6xl--line-height: 1;
+  --text-6xl--letter-spacing: -0.028em;
+  --text-7xl: 4.5rem;
+  --text-7xl--line-height: 1;
+  --text-7xl--letter-spacing: -0.03em;
+}

package/tokens/src/tokens.css

@@ -23,11 +23,15 @@
  * modal / tabs motion variables. Every rule sits in a Tailwind layer and the
  * timings and strengths are `:root` variables, so app rules and app `:root`
  * values win.
+ *
+ * It also brings the `text-*` type scale with size-specific
+ * tracking (css/type-scale.css), including the `3xs`, `2xs` and `2sm` tiers.
  */
 
 @import "./css/clear-input.css";
 @import "./css/scrollbar-thin.css";
 @import "./css/motion.css";
+@import "./css/type-scale.css";
 
 @custom-variant dark (&:where(.dark, .dark *));