@remix-run/ui 0.2.0 → 0.3.0

package/src/animation/demos/spring.demo.tsx

@@ -0,0 +1,385 @@
+import { addEventListeners, css, on, ref, type Handle } from '@remix-run/ui'
+
+import { dragVelocityEvents } from './drag-release.ts'
+import { spring, type SpringPreset } from '@remix-run/ui/animation'
+
+interface TrailPoint {
+  x: number
+  y: number
+  time: number
+}
+
+function PointerTrail(handle: Handle) {
+  let canvas: HTMLCanvasElement
+  let points: TrailPoint[] = []
+  let isDown = false
+  let releaseTime = 0
+  let animationId: number | null = null
+
+  let maxAge = 150 // ms - how long points stay in the trail while dragging
+  let fadeDuration = 800 // ms - how long the trail fades after release
+
+  function draw() {
+    if (!canvas) return
+    let ctx = canvas.getContext('2d')
+    if (!ctx) return
+
+    let now = performance.now()
+    ctx.clearRect(0, 0, canvas.width, canvas.height)
+
+    // Calculate overall opacity based on release time
+    let overallOpacity = 1
+    if (!isDown && releaseTime > 0) {
+      let elapsed = now - releaseTime
+      overallOpacity = Math.max(0, 1 - elapsed / fadeDuration)
+      if (overallOpacity <= 0) {
+        points = []
+        animationId = null
+        return
+      }
+    }
+
+    // Filter out old points while dragging
+    if (isDown) {
+      points = points.filter((p) => now - p.time < maxAge)
+    }
+
+    if (points.length < 2) {
+      if (isDown || overallOpacity > 0) {
+        animationId = requestAnimationFrame(draw)
+      } else {
+        animationId = null
+      }
+      return
+    }
+
+    // Draw the trail as a tapered path
+    ctx.beginPath()
+    ctx.lineCap = 'round'
+    ctx.lineJoin = 'round'
+
+    for (let i = 1; i < points.length; i++) {
+      let prev = points[i - 1]
+      let curr = points[i]
+
+      // Age-based opacity (older = more transparent)
+      let age = isDown ? (now - prev.time) / maxAge : 0
+      let segmentOpacity = (1 - age) * overallOpacity
+
+      // Thickness tapers from thin (old) to thick (new)
+      let progress = i / (points.length - 1)
+      let thickness = 2 + progress * 8
+
+      ctx.beginPath()
+      ctx.moveTo(prev.x, prev.y)
+      ctx.lineTo(curr.x, curr.y)
+      ctx.strokeStyle = `rgba(14, 165, 233, ${segmentOpacity * 0.6})`
+      ctx.lineWidth = thickness
+      ctx.stroke()
+    }
+
+    // Draw a red glow at the end to show direction
+    if (points.length > 0) {
+      let last = points[points.length - 1]
+      let gradient = ctx.createRadialGradient(last.x, last.y, 0, last.x, last.y, 20)
+      gradient.addColorStop(0, `rgba(239, 68, 68, ${overallOpacity * 0.6})`)
+      gradient.addColorStop(1, 'rgba(239, 68, 68, 0)')
+      ctx.fillStyle = gradient
+      ctx.beginPath()
+      ctx.arc(last.x, last.y, 20, 0, Math.PI * 2)
+      ctx.fill()
+    }
+
+    animationId = requestAnimationFrame(draw)
+  }
+
+  function startDrawing() {
+    if (!animationId) {
+      animationId = requestAnimationFrame(draw)
+    }
+  }
+
+  if (typeof document !== 'undefined') {
+    addEventListeners(document, handle.signal, {
+      pointerdown(event) {
+        if (!(event.target as HTMLElement).closest('.draggable')) return
+        isDown = true
+        releaseTime = 0
+        points = [{ x: event.clientX, y: event.clientY, time: performance.now() }]
+        startDrawing()
+      },
+
+      pointermove(event) {
+        if (!isDown) return
+        points.push({ x: event.clientX, y: event.clientY, time: performance.now() })
+      },
+
+      pointerup() {
+        if (!isDown) return
+        isDown = false
+        releaseTime = performance.now()
+      },
+
+      pointercancel() {
+        isDown = false
+        releaseTime = performance.now()
+      },
+    })
+  }
+
+  return () => (
+    <canvas
+      mix={[
+        ref((node) => {
+          canvas = node
+          canvas.width = window.innerWidth
+          canvas.height = window.innerHeight
+        }),
+        css({
+          position: 'absolute',
+          inset: 0,
+          pointerEvents: 'none',
+          zIndex: 5,
+        }),
+      ]}
+    />
+  )
+}
+
+/**
+ * @name Spring Drag Release
+ * @description A full-screen spring physics playground with click targets and drag-release velocity.
+ */
+export default function SpringDemo(handle: Handle) {
+  let viewportWidth = globalThis.window?.innerWidth ?? 1000
+  let viewportHeight = globalThis.window?.innerHeight ?? 700
+
+  // Target circle position (click to move)
+  let targetX = viewportWidth / 2
+  let targetY = viewportHeight / 2
+
+  // Draggable circle state
+  let dragX = viewportWidth / 2 - 150
+  let dragY = viewportHeight / 2
+  let isDragging = false
+  let isAnimating = false
+
+  // Current spring transitions (separate for X and Y to capture 2D velocity)
+  let transitionX = ''
+  let transitionY = ''
+
+  let selectedPreset: SpringPreset = 'bouncy'
+
+  // Get default spring transition for target circle
+  let springValue = spring(selectedPreset)
+
+  if (typeof document !== 'undefined') {
+    addEventListeners(document, handle.signal, {
+      click(event) {
+        // Ignore clicks on controls or when dragging
+        if ((event.target as HTMLElement).closest('.controls')) return
+        if ((event.target as HTMLElement).closest('.draggable')) return
+
+        targetX = event.clientX
+        targetY = event.clientY
+        handle.update()
+      },
+    })
+  }
+
+  return () => (
+    <div
+      mix={[
+        css({
+          position: 'fixed',
+          inset: 0,
+          backgroundColor: '#1a1a2e',
+          cursor: 'crosshair',
+          overflow: 'hidden',
+        }),
+      ]}
+    >
+      {/* Pointer trail */}
+      <PointerTrail />
+
+      {/* Target circle */}
+      <div
+        mix={[
+          css({
+            position: 'absolute',
+            width: '80px',
+            height: '80px',
+            borderRadius: '50%',
+            backgroundColor: 'transparent',
+            border: '3px dashed rgba(233, 69, 96, 0.5)',
+            transform: 'translate(-50%, -50%)',
+            pointerEvents: 'none',
+          }),
+        ]}
+        style={{
+          left: `${targetX}px`,
+          top: `${targetY}px`,
+          transition: `left ${springValue}, top ${springValue}`,
+        }}
+      />
+
+      {/* Draggable circle */}
+      <div
+        className="draggable"
+        mix={[
+          css({
+            position: 'absolute',
+            width: '60px',
+            height: '60px',
+            borderRadius: '50%',
+            backgroundColor: '#0ea5e9',
+            boxShadow: '0 0 20px rgba(14, 165, 233, 0.5)',
+            transform: 'translate(-50%, -50%)',
+            userSelect: 'none',
+            touchAction: 'none',
+            zIndex: 10,
+          }),
+          on('transitionend', () => {
+            isAnimating = false
+            handle.update()
+          }),
+          on('pointerdown', (event) => {
+            event.preventDefault()
+            isDragging = true
+            isAnimating = false
+            handle.update()
+          }),
+          on('pointermove', (event) => {
+            if (!isDragging) return
+            dragX = event.clientX
+            dragY = event.clientY
+            handle.update()
+          }),
+          dragVelocityEvents(),
+          on(dragVelocityEvents.release, (event) => {
+            isDragging = false
+
+            // Calculate distance to target on each axis
+            let distX = targetX - dragX
+            let distY = targetY - dragY
+
+            if (Math.abs(distX) < 1 && Math.abs(distY) < 1) {
+              handle.update()
+              return
+            }
+
+            // Create separate springs for X and Y with their own normalized velocities
+            // normalizedVelocity = velocity / distance (with sign!) for each axis
+            // The sign matters: positive = moving toward target, negative = moving away
+            if (Math.abs(distX) >= 1) {
+              let normalizedVelocityX = event.velocityX / distX
+              normalizedVelocityX = Math.max(-20, Math.min(20, normalizedVelocityX))
+              transitionX = String(spring(selectedPreset, { velocity: normalizedVelocityX }))
+            } else {
+              transitionX = String(spring(selectedPreset))
+            }
+
+            if (Math.abs(distY) >= 1) {
+              let normalizedVelocityY = event.velocityY / distY
+              normalizedVelocityY = Math.max(-20, Math.min(20, normalizedVelocityY))
+              transitionY = String(spring(selectedPreset, { velocity: normalizedVelocityY }))
+            } else {
+              transitionY = String(spring(selectedPreset))
+            }
+
+            // Animate to target
+            isAnimating = true
+            dragX = targetX
+            dragY = targetY
+            handle.update()
+          }),
+        ]}
+        style={{
+          left: `${dragX}px`,
+          top: `${dragY}px`,
+          cursor: isDragging ? 'grabbing' : 'grab',
+          transition: isAnimating ? `left ${transitionX}, top ${transitionY}` : 'none',
+        }}
+      />
+
+      {/* Controls */}
+      <div
+        className="controls"
+        mix={[
+          css({
+            position: 'absolute',
+            top: '20px',
+            left: '50%',
+            transform: 'translateX(-50%)',
+            display: 'flex',
+            gap: '4px',
+            padding: '4px',
+            backgroundColor: 'rgba(255, 255, 255, 0.1)',
+            borderRadius: '8px',
+            fontFamily: 'system-ui, sans-serif',
+            fontSize: '14px',
+            cursor: 'default',
+          }),
+        ]}
+      >
+        {(Object.keys(spring.presets) as SpringPreset[]).map((preset) => (
+          <label
+            key={preset}
+            mix={[
+              css({
+                display: 'flex',
+                alignItems: 'center',
+                gap: '6px',
+                padding: '8px 12px',
+                borderRadius: '6px',
+                color: '#fff',
+                cursor: 'pointer',
+                transition: 'background-color 150ms ease',
+                '&:hover': {
+                  backgroundColor: 'rgba(255, 255, 255, 0.1)',
+                },
+                '&:has(input:checked)': {
+                  backgroundColor: 'rgba(14, 165, 233, 0.3)',
+                },
+              }),
+            ]}
+          >
+            <input
+              type="radio"
+              name="spring-preset"
+              value={preset}
+              checked={selectedPreset === preset}
+              mix={[
+                css({ accentColor: '#0ea5e9' }),
+                on('change', () => {
+                  selectedPreset = preset
+                  springValue = spring(selectedPreset)
+                  handle.update()
+                }),
+              ]}
+            />
+            {preset}
+          </label>
+        ))}
+      </div>
+
+      {/* Instructions */}
+      <div
+        mix={[
+          css({
+            position: 'absolute',
+            bottom: '20px',
+            left: '50%',
+            transform: 'translateX(-50%)',
+            color: '#ffffff80',
+            fontFamily: 'system-ui, sans-serif',
+            fontSize: '14px',
+            textAlign: 'center',
+          }),
+        ]}
+      >
+        Click to move target • Drag the blue circle and release to see velocity-based spring
+      </div>
+    </div>
+  )
+}

package/src/animation/demos/transition-options.tsx

@@ -0,0 +1,24 @@
+import { css } from '@remix-run/ui'
+import { animateEntrance } from '@remix-run/ui/animation'
+
+export function TransitionOptions() {
+  return () => (
+    <div
+      mix={[
+        css({
+          width: 100,
+          height: 100,
+          borderRadius: '50%',
+          backgroundColor: '#9911ff',
+        }),
+        animateEntrance({
+          opacity: 0,
+          transform: 'scale(0.5)',
+          duration: 800,
+          delay: 500,
+          easing: 'cubic-bezier(0, 0.71, 0.2, 1.01)',
+        }),
+      ]}
+    />
+  )
+}

package/src/animation/spring.ts

@@ -144,6 +144,28 @@ function transition(
   return properties.map((p) => `${p} ${s}`).join(', ')
 }
 
+/**
+ * Create a spring-physics animation iterator for CSS transitions and WAAPI.
+ *
+ * The returned iterator can be:
+ * - Iterated to get position values (0→1)
+ * - Spread into WAAPI options: `element.animate(keyframes, { ...spring() })`
+ * - Stringified for CSS: `` `transform ${spring()}` ``
+ *
+ * @example
+ * // Named preset
+ * let s = spring('bouncy')
+ * element.style.transition = `transform ${s}`
+ *
+ * @example
+ * // Custom parameters
+ * let s = spring({ duration: 500, bounce: 0.2 })
+ * element.animate(keyframes, { ...s })
+ *
+ * @example
+ * // Transition helper for multiple properties
+ * element.style.transition = spring.transition(['transform', 'opacity'], 'snappy')
+ */
 export const spring: SpringFunction = Object.assign(createSpring, {
   transition,
   presets,

package/src/components/accordion/demos/card.demo.tsx

@@ -10,6 +10,7 @@ import { theme } from '@remix-run/ui/theme'
 /**
  * @name Accordion in a Card
  * @description The Accordion can sit inside a card when the surrounding surface needs stronger grouping.
+ * @layout center
  * @order 3
  */
 export default function Example() {

package/src/components/accordion/demos/multiple.demo.tsx

@@ -11,6 +11,7 @@ import { theme } from '@remix-run/ui/theme'
  * @order 2
  * @name Accordion Multiple Open
  * @description Multiple mode allows several sections to stay open simultaneously, useful for operational checklists and dashboards.
+ * @layout center
  */
 export default function Example() {
   return () => (

package/src/components/accordion/demos/overview.demo.tsx

@@ -10,6 +10,7 @@ import { theme } from '@remix-run/ui/theme'
 /**
  * @name Accordion Overview
  * @description A single-open disclosure list that keeps settings, billing, or notification rules in one calm section.
+ * @layout center
  * @order 1
  */
 export default function Example() {

package/src/components/anchor/README.md

@@ -1,6 +1,6 @@
 # anchor
 
-`anchor` positions a floating element against an anchor element and keeps it constrained to the viewport. Use it for custom floating surfaces that need placement, flipping, offsets, and optional relative alignment.
+`anchor` positions a floating element against an anchor element or viewport coordinates and keeps it constrained to the viewport. Use it for custom floating surfaces that need placement, flipping, offsets, and optional relative alignment.
 
 ## Usage
 
@@ -49,11 +49,19 @@ popover.addEventListener('beforetoggle', (event) => {
 })
 ```
 
+Anchor to coordinates when the surface should open at a pointer location.
+
+```tsx
+let cleanup = anchor(popover, { x: event.clientX, y: event.clientY }, { placement: 'bottom-start' })
+```
+
 ## `anchor.*`
 
-- `anchor(floatingElement, anchorElement, options)`: positions `floatingElement` against `anchorElement`, starts animation-frame polling for geometry changes, and returns a cleanup function.
+- `anchor(floatingElement, anchorTarget, options)`: positions `floatingElement` against an element or coordinate target, starts animation-frame polling for geometry changes, and returns a cleanup function.
 - `AnchorOptions`: placement, inset, relative alignment, and offset options.
+- `AnchorPoint`: viewport coordinate target with `x`, `y`, and optional `width`/`height`.
 - `AnchorPlacement`: exported placement names for the main sides and top/bottom start/end alignment.
+- `AnchorTarget`: an `HTMLElement` or `AnchorPoint`.
 
 ## Placements
 
@@ -149,5 +157,5 @@ anchor(listbox, trigger, {
 - Oversized inset surfaces with `relativeTo` preserve alignment by scrolling the nearest scrollable descendant when possible.
 - `offset`, `offsetX`, and `offsetY` may be numbers or functions that receive the floating element.
 - `relativeTo` lets a surface align to an inner element, which is useful for selected options inside popovers.
-- `anchor` polls on animation frames for anchor or floating geometry changes and repositions when either changes.
+- `anchor` polls on animation frames for anchor target or floating geometry changes and repositions when either changes.
 - The returned cleanup function cancels animation-frame polling.

package/src/components/anchor/anchor.ts

@@ -24,6 +24,15 @@ export type AnchorPlacement =
 
 type AnchorOffsetValue = number | ((floating: HTMLElement) => number)
 
+export interface AnchorPoint {
+  height?: number
+  width?: number
+  x: number
+  y: number
+}
+
+export type AnchorTarget = HTMLElement | AnchorPoint
+
 export type AnchorOptions = {
   placement?: ExtendedAnchorPlacement
   inset?: boolean
@@ -125,6 +134,39 @@ function resolveOffsetValue(offset: AnchorOffsetValue | undefined, floating: HTM
   return offset ?? 0
 }
 
+function isAnchorPoint(value: unknown): value is AnchorPoint {
+  if (typeof value !== 'object' || value === null) {
+    return false
+  }
+
+  if (!('x' in value) || !('y' in value)) {
+    return false
+  }
+
+  let width = 'width' in value ? value.width : undefined
+  let height = 'height' in value ? value.height : undefined
+
+  return (
+    typeof value.x === 'number' &&
+    typeof value.y === 'number' &&
+    (width === undefined || typeof width === 'number') &&
+    (height === undefined || typeof height === 'number')
+  )
+}
+
+function readAnchorRect(anchorTarget: AnchorTarget) {
+  if (anchorTarget instanceof HTMLElement) {
+    return anchorTarget.getBoundingClientRect()
+  }
+
+  return new DOMRect(
+    anchorTarget.x,
+    anchorTarget.y,
+    anchorTarget.width ?? 0,
+    anchorTarget.height ?? 0,
+  )
+}
+
 function calculatePosition(
   placement: ExtendedAnchorPlacement,
   anchorRect: DOMRect,
@@ -468,7 +510,7 @@ function getFlippedPlacement(
   placementHeight: number,
   collisionWidth: number,
   collisionHeight: number,
-  anchor: HTMLElement,
+  anchorIsAbsolutePositioned: boolean,
   inset: boolean,
   offset: number,
   offsetX: number,
@@ -476,11 +518,9 @@ function getFlippedPlacement(
   relativeOffsetX?: number | null,
   relativeOffsetY?: number | null,
 ) {
-  let computedStyle = getComputedStyle(anchor)
-  let isAbsolutePositioned = computedStyle.position !== 'fixed'
   let hasScroll = window.scrollY > 0
 
-  if (placement.startsWith('top') && isAbsolutePositioned && hasScroll) {
+  if (placement.startsWith('top') && anchorIsAbsolutePositioned && hasScroll) {
     if (anchorRect.top - placementHeight < 0) {
       return placement
     }
@@ -641,7 +681,7 @@ function solveRelativeAlignmentAxis(options: {
 
 export function anchor(
   floating: HTMLElement,
-  anchorElement: HTMLElement,
+  anchorTarget: AnchorTarget,
   options: AnchorOptions = {},
 ): () => void {
   let lastAnchorRect: DOMRect
@@ -651,8 +691,8 @@ export function anchor(
     throw new TypeError('anchor() expected a floating HTMLElement')
   }
 
-  if (!(anchorElement instanceof HTMLElement)) {
-    throw new TypeError('anchor() expected an anchor HTMLElement')
+  if (!(anchorTarget instanceof HTMLElement) && !isAnchorPoint(anchorTarget)) {
+    throw new TypeError('anchor() expected an anchor HTMLElement or coordinates')
   }
 
   let {
@@ -664,12 +704,13 @@ export function anchor(
     offsetY: rawOffsetY = 0,
   } = options
 
-  let isFixed =
-    floating.hasAttribute('popover') || getComputedStyle(anchorElement).position === 'fixed'
+  let anchorIsAbsolutePositioned =
+    anchorTarget instanceof HTMLElement && getComputedStyle(anchorTarget).position !== 'fixed'
+  let isFixed = floating.hasAttribute('popover') || !anchorIsAbsolutePositioned
   let animationFrameId = 0
 
   function updatePosition(
-    anchorRect = anchorElement.getBoundingClientRect(),
+    anchorRect = readAnchorRect(anchorTarget),
     naturalDimensions = getFloatingDimensions(floating, relativeTo, {
       ignoreInlineMaxSize: true,
     }),
@@ -695,7 +736,7 @@ export function anchor(
       placementHeight,
       naturalDimensions.width,
       naturalDimensions.height,
-      anchorElement,
+      anchorIsAbsolutePositioned,
       inset,
       offset,
       offsetX,
@@ -872,7 +913,7 @@ export function anchor(
   updatePosition()
 
   function pollForPositionChanges() {
-    let currentRect = anchorElement.getBoundingClientRect()
+    let currentRect = readAnchorRect(anchorTarget)
     let currentDimensions = getFloatingDimensions(floating, relativeTo)
     if (
       hasRectChanged(currentRect, lastAnchorRect) ||

package/src/components/breadcrumbs/{demos/basic.demo.tsx → basic.demo.tsx}

@@ -3,6 +3,7 @@ import { Breadcrumbs } from '@remix-run/ui/breadcrumbs'
 /**
  * @name Breadcrumbs Basic
  * @description A basic breadcrumb trail linking back through the page hierarchy.
+ * @layout center
  */
 export default function Example() {
   return () => (

package/src/components/breadcrumbs/{demos/separator.demo.tsx → separator.demo.tsx}

@@ -3,6 +3,7 @@ import { Breadcrumbs } from '@remix-run/ui/breadcrumbs'
 /**
  * @name Breadcrumbs with Separator
  * @description Pass a custom separator string to override the default chevron icon.
+ * @layout center
  */
 export default function Example() {
   return () => (

package/src/components/button/demos/aliases.demo.tsx

@@ -5,6 +5,7 @@ import { theme } from '@remix-run/ui/theme'
 /**
  * @name Button Component
  * @description The Button component wraps the low-level style primitives and accepts a tone prop for quick theming.
+ * @layout center
  * @order 2
  */
 export default function Example() {

package/src/components/button/demos/basic.demo.tsx

@@ -6,6 +6,7 @@ import { theme } from '@remix-run/ui/theme'
 /**
  * @name Basic Button
  * @description The default button contract supports both ordinary actions and link-shaped navigation.
+ * @layout center
  * @order 1
  */
 export default function Example() {

package/src/components/button/demos/states.demo.tsx

@@ -6,6 +6,7 @@ import { theme } from '@remix-run/ui/theme'
 /**
  * @name Button States
  * @description Buttons support normal, disabled, and busy (loading) states using aria attributes.
+ * @layout center
  * @order 3
  */
 export default function Example() {

package/src/components/combobox/{demos/overview.demo.tsx → overview.demo.tsx}

@@ -5,6 +5,7 @@ import { theme } from '@remix-run/ui/theme'
 /**
  * @name Combobox Overview
  * @description A searchable combobox with keyboard navigation. Try typing airport names or codes like ord, lax, or jfk.
+ * @layout center
  */
 export default function Example(handle: Handle) {
   let value: string | null = null

package/src/components/listbox/{demos/overview.demo.tsx → overview.demo.tsx}

@@ -7,6 +7,7 @@ import { theme } from '@remix-run/ui/theme'
 /**
  * @name Listbox Overview
  * @description A keyboard-navigable listbox with selection, highlighting, and an optional flash-selection animation.
+ * @layout center
  */
 export default function Example(handle: Handle) {
   let value: ListboxValue = options[0]!.value