@glyphui/ui 0.4.0 → 0.5.0

package/src/motion/motion-root.tsx

@@ -0,0 +1,46 @@
+import { LazyMotion, MotionConfig } from 'motion/react'
+import { type ReactNode, useEffect } from 'react'
+import { useMotionSettings } from './use-motion-settings'
+
+const loadFeatures = () => import('./features').then((mod) => mod.default)
+const instant = { duration: 0 } as const
+
+/**
+ * Connects the `motion` library to the theme: one lazily loaded feature bundle, the theme's
+ * spring as the default transition, and instant transitions when motion is off.
+ */
+export function MotionScope({ children }: { children: ReactNode }) {
+  const { animate, spring } = useMotionSettings()
+  return (
+    <LazyMotion features={loadFeatures}>
+      <MotionConfig reducedMotion="user" transition={animate ? spring : instant}>
+        {children}
+      </MotionConfig>
+    </LazyMotion>
+  )
+}
+
+/** Mirrors the effective motion level onto `<html data-motion>` so CSS animations follow it. */
+export function MotionRootAttribute() {
+  const { level } = useMotionSettings()
+  useEffect(() => {
+    const root = document.documentElement
+    const previous = root.getAttribute('data-motion')
+    root.setAttribute('data-motion', level)
+    return () => {
+      if (previous === null) root.removeAttribute('data-motion')
+      else root.setAttribute('data-motion', previous)
+    }
+  }, [level])
+  return null
+}
+
+/** Inside a `ThemeScope`: `motion` transitions use that theme's spring and level. */
+export function ScopedMotionConfig({ children }: { children: ReactNode }) {
+  const { animate, spring } = useMotionSettings()
+  return (
+    <MotionConfig reducedMotion="user" transition={animate ? spring : instant}>
+      {children}
+    </MotionConfig>
+  )
+}

package/src/motion/page-transition.tsx

@@ -0,0 +1,30 @@
+import { type ComponentProps, useEffect, useRef } from 'react'
+import { cn } from '../utils/cn'
+
+export interface PageTransitionProps extends ComponentProps<'div'> {
+  /**
+   * Changes when the page changes, e.g. `location.pathname`. Each new value replays the
+   * entrance; the first page renders without one.
+   */
+  transitionKey: string
+}
+
+/**
+ * Fades and lifts each new page in on route changes. Wrap your router outlet:
+ * `<PageTransition transitionKey={useLocation().pathname}><Outlet /></PageTransition>`.
+ * Enter-only by design: the old page leaves immediately, so nothing ever overlaps or flickers.
+ */
+export function PageTransition({ transitionKey, className, ...props }: PageTransitionProps) {
+  const mounted = useRef(false)
+  useEffect(() => {
+    mounted.current = true
+  }, [])
+  return (
+    <div
+      key={transitionKey}
+      data-slot="page-transition"
+      className={cn(mounted.current && 'animate-page-in', className)}
+      {...props}
+    />
+  )
+}

package/src/motion/presence-list.tsx

@@ -0,0 +1,42 @@
+import { AnimatePresence, m } from 'motion/react'
+import type { ComponentProps, ReactNode } from 'react'
+import { useMotionSettings } from './use-motion-settings'
+
+/**
+ * Animates items of a list in and out, and slides the rest into place. Children must be
+ * keyed `PresenceItem`s. Renders the list statically when motion is off.
+ */
+export function PresenceList({ children }: { children: ReactNode }) {
+  const { animate } = useMotionSettings()
+  if (!animate) return children
+  return <AnimatePresence initial={false}>{children}</AnimatePresence>
+}
+
+type PresenceItemProps<T extends 'li' | 'span'> = ComponentProps<T> & { as?: T }
+
+const enter = { opacity: 0, scale: 0.96 }
+const shown = { opacity: 1, scale: 1 }
+const leave = { opacity: 0, scale: 0.96, transition: { duration: 0.12 } }
+
+/** One item of a `PresenceList`: fades and scales in, out, and between positions. */
+export function PresenceItem<T extends 'li' | 'span' = 'li'>({
+  as,
+  ...props
+}: PresenceItemProps<T>) {
+  const { animate } = useMotionSettings()
+  const tag = (as ?? 'li') as 'li' | 'span'
+  if (!animate) {
+    const Static = tag
+    return <Static {...(props as ComponentProps<'li'>)} />
+  }
+  const Animated = (tag === 'li' ? m.li : m.span) as typeof m.li
+  return (
+    <Animated
+      layout="position"
+      initial={enter}
+      animate={shown}
+      exit={leave}
+      {...(props as ComponentProps<typeof m.li>)}
+    />
+  )
+}

package/src/motion/presence.tsx

@@ -0,0 +1,13 @@
+import { AnimatePresence } from 'motion/react'
+import type { ComponentProps } from 'react'
+
+export type PresenceProps = ComponentProps<typeof AnimatePresence>
+
+/**
+ * `motion`'s AnimatePresence with Glyph's defaults: children already on screen when the
+ * page loads don't animate in (`initial={false}`). Use it with `m.*` elements for custom
+ * enter and exit animations; transitions follow the theme's spring.
+ */
+export function Presence({ initial = false, ...props }: PresenceProps) {
+  return <AnimatePresence initial={initial} {...props} />
+}

package/src/motion/reveal.tsx

@@ -0,0 +1,50 @@
+import { Slot } from 'radix-ui'
+import { type ComponentProps, type CSSProperties, useRef } from 'react'
+import { composeRefs } from '../utils/compose-refs'
+import { type RevealOptions, useReveal } from './use-reveal'
+
+export interface RevealProps extends ComponentProps<'div'>, RevealOptions {
+  /** Delay before the entrance starts, in milliseconds. */
+  delay?: number
+  /** Distance it rises from, in px or any CSS length. Defaults to the motion level's. */
+  y?: number | string
+  /** Start slightly smaller, for cards and media. */
+  scale?: boolean
+  asChild?: boolean
+}
+
+const length = (value: number | string) => (typeof value === 'number' ? `${value}px` : value)
+
+/**
+ * Fades and rises its content in when it scrolls into view. Uses the theme's spring, follows
+ * the motion level, and leaves content visible when motion is off or JavaScript hasn't run.
+ */
+export function Reveal({
+  delay,
+  y,
+  scale,
+  once,
+  amount,
+  enabled,
+  asChild,
+  style,
+  ref,
+  ...props
+}: RevealProps) {
+  const local = useRef<HTMLDivElement>(null)
+  useReveal(local, 'reveal', { once, amount, enabled })
+  const Comp = asChild ? Slot.Root : 'div'
+  const vars = {
+    ...(delay !== undefined && { '--glyph-reveal-delay': `${delay}ms` }),
+    ...(y !== undefined && { '--glyph-reveal-y': length(y) }),
+    ...(scale && { '--glyph-reveal-scale': 'var(--glyph-motion-scale)' }),
+  } as CSSProperties
+  return (
+    <Comp
+      data-slot="reveal"
+      ref={composeRefs(local, ref)}
+      style={{ ...vars, ...style }}
+      {...props}
+    />
+  )
+}

package/src/motion/stagger.tsx

@@ -0,0 +1,81 @@
+import { Slot } from 'radix-ui'
+import {
+  Children,
+  type ComponentProps,
+  type CSSProperties,
+  isValidElement,
+  type ReactNode,
+  useRef,
+} from 'react'
+import { composeRefs } from '../utils/compose-refs'
+import { type RevealOptions, useReveal } from './use-reveal'
+
+type StaggerElement = 'div' | 'ul' | 'ol' | 'dl' | 'section'
+
+export interface StaggerProps extends ComponentProps<'div'>, RevealOptions {
+  /** The element to render, e.g. `ul` for a list whose `li` items cascade in. Default `div`. */
+  as?: StaggerElement
+  /** Milliseconds between one child and the next. Defaults to the motion level's step. */
+  step?: number
+  /** Milliseconds before the first child. */
+  delay?: number
+  asChild?: boolean
+}
+
+/**
+ * Reveals its children one after another when the group scrolls into view: feature grids,
+ * pricing tiers, card lists. Each direct child becomes a `StaggerItem` without a wrapper.
+ */
+export function Stagger({
+  step,
+  delay,
+  once,
+  amount,
+  enabled,
+  as = 'div',
+  asChild,
+  style,
+  children,
+  ref,
+  ...props
+}: StaggerProps) {
+  const local = useRef<HTMLDivElement>(null)
+  useReveal(local, 'stagger', { once, amount, enabled })
+  const Comp = (asChild ? Slot.Root : as) as 'div'
+  const vars = {
+    ...(step !== undefined && { '--glyph-stagger-step': `${step}ms` }),
+    ...(delay !== undefined && { '--glyph-stagger-delay': `${delay}ms` }),
+  } as CSSProperties
+  let index = 0
+  const items = Children.map(children, (child) =>
+    isValidElement(child) ? <StaggerItem index={index++}>{child}</StaggerItem> : child,
+  )
+  return (
+    <Comp
+      data-slot="stagger"
+      ref={composeRefs(local, ref)}
+      style={{ ...vars, ...style }}
+      {...props}
+    >
+      {asChild ? children : items}
+    </Comp>
+  )
+}
+
+export interface StaggerItemProps {
+  /** Position in the cascade, starting at 0. */
+  index: number
+  children: ReactNode
+}
+
+/**
+ * One step of a `Stagger`, for children that are not direct (e.g. inside a fragment or a
+ * mapped list with wrappers). Merges onto its child; renders no element of its own.
+ */
+export function StaggerItem({ index, children }: StaggerItemProps) {
+  return (
+    <Slot.Root data-stagger-item="" style={{ '--glyph-stagger-index': index } as CSSProperties}>
+      {children}
+    </Slot.Root>
+  )
+}

package/src/motion/use-motion-settings.ts

@@ -0,0 +1,52 @@
+import type { MotionLevel, SpringConfig } from '@glyphui/tokens'
+import { useContext, useMemo } from 'react'
+import { useMediaQuery } from '../hooks/use-media-query'
+import { GlyphContext } from '../provider/glyph-context'
+
+export interface MotionSettings {
+  /** The effective level: the theme's, overridden by the provider, forced to `none` by reduced motion. */
+  level: MotionLevel
+  /** `false` when level is `none`. Components render static markup then. */
+  animate: boolean
+  /** The theme's spring for overlays, indicators and layout animations. */
+  spring: SpringConfig & { type: 'spring' }
+  /** Theme durations in seconds, for tween animations. */
+  duration: { fast: number; base: number; slow: number }
+}
+
+const defaultSpring: SpringConfig = { stiffness: 420, damping: 34 }
+
+function seconds(value: string | undefined, fallback: number): number {
+  if (!value) return fallback
+  const n = Number.parseFloat(value)
+  if (Number.isNaN(n)) return fallback
+  return value.trim().endsWith('ms') ? n / 1000 : n
+}
+
+/**
+ * How Glyph components should animate right now. Every animated component reads this, so a
+ * theme's `motion.level`, the provider's `motion` prop and the visitor's reduced-motion
+ * setting control all motion in one place.
+ */
+export function useMotionSettings(): MotionSettings {
+  const context = useContext(GlyphContext)
+  const reduced = useMediaQuery('(prefers-reduced-motion: reduce)')
+  const motion = context?.theme.motion
+  const level: MotionLevel = reduced ? 'none' : (context?.motion ?? motion?.level ?? 'subtle')
+  const spring = motion?.spring ?? defaultSpring
+  const durations = motion?.duration
+  // Stable identity per theme, so components can depend on these in effects.
+  return useMemo(
+    () => ({
+      level,
+      animate: level !== 'none',
+      spring: { type: 'spring' as const, ...spring },
+      duration: {
+        fast: seconds(durations?.fast, 0.12),
+        base: seconds(durations?.base, 0.18),
+        slow: seconds(durations?.slow, 0.28),
+      },
+    }),
+    [level, spring, durations],
+  )
+}

package/src/motion/use-reveal.ts

@@ -0,0 +1,54 @@
+import { type RefObject, useEffect, useLayoutEffect } from 'react'
+import { useMotionSettings } from './use-motion-settings'
+
+const useIsomorphicLayoutEffect = typeof window === 'undefined' ? useEffect : useLayoutEffect
+
+export interface RevealOptions {
+  /** Animate only the first time it scrolls into view. Default true. */
+  once?: boolean | undefined
+  /** Share of the element that must be visible, 0–1. Default 0.15. */
+  amount?: number | undefined
+  /** Set false to show the content without animating. */
+  enabled?: boolean | undefined
+}
+
+/**
+ * Drives a `data-<attribute>="hidden|shown"` attribute from an IntersectionObserver.
+ *
+ * Content stays visible unless everything needed to reveal it is available: motion is on,
+ * the browser has IntersectionObserver, and JavaScript ran. Server HTML, tests and
+ * reduced-motion visitors always get visible content.
+ */
+export function useReveal(
+  ref: RefObject<HTMLElement | null>,
+  attribute: 'reveal' | 'stagger',
+  { once = true, amount = 0.15, enabled = true }: RevealOptions = {},
+): void {
+  const { animate } = useMotionSettings()
+  const active = enabled && animate
+
+  // Hide before the first paint, so in-view content animates in instead of flashing.
+  useIsomorphicLayoutEffect(() => {
+    const el = ref.current
+    if (!el || !active || typeof IntersectionObserver === 'undefined') return
+    const key = `data-${attribute}`
+    el.setAttribute(key, 'hidden')
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        if (!entry) return
+        if (entry.isIntersecting) {
+          el.setAttribute(key, 'shown')
+          if (once) observer.disconnect()
+        } else if (!once) {
+          el.setAttribute(key, 'hidden')
+        }
+      },
+      { threshold: amount },
+    )
+    observer.observe(el)
+    return () => {
+      observer.disconnect()
+      el.removeAttribute(key)
+    }
+  }, [active, attribute, once, amount])
+}

package/src/patterns/app-shell/app-shell.styles.ts

@@ -1,7 +1,7 @@
 import { focusRing, transition } from '../../utils/styles'
 import { tv, type VariantProps } from '../../utils/tv'
 
-export const appShellStyles = tv({
+export const appShellStyles = /* @__PURE__ */ tv({
   slots: {
     root: 'flex w-full bg-background',
     sidebar: 'hidden shrink-0 md:flex',
@@ -10,9 +10,10 @@ export const appShellStyles = tv({
       'flex h-14 shrink-0 items-center gap-2 border-b-border px-3 md:hidden',
       'border-b-(length:--glyph-border-width)',
     ],
-    overlay: 'fixed inset-0 z-50 animate-fade-in bg-overlay',
+    overlay:
+      'fixed inset-0 z-50 bg-overlay data-[state=open]:animate-fade-in data-[state=closed]:animate-fade-out',
     drawer:
-      'fixed inset-y-0 left-0 z-50 flex w-72 max-w-[85vw] animate-slide-in-left shadow-lg outline-none [&>[data-slot=sidebar]]:w-full',
+      'fixed inset-y-0 left-0 z-50 flex w-72 max-w-[85vw] shadow-lg data-[state=open]:animate-sheet-in-left data-[state=closed]:animate-sheet-out-left outline-none [&>[data-slot=sidebar]]:w-full',
   },
   variants: {
     layout: {
@@ -33,10 +34,11 @@ export const appShellStyles = tv({
 
 export type AppShellVariants = VariantProps<typeof appShellStyles>
 
-export const sidebarStyles = tv({
+export const sidebarStyles = /* @__PURE__ */ tv({
   slots: {
     root: [
-      'group/sidebar flex h-full w-60 flex-col overflow-hidden border-r-border bg-subtle',
+      // Isolated so the active item's sliding highlight stays under every item's label.
+      'group/sidebar isolate flex h-full w-60 flex-col overflow-hidden border-r-border bg-subtle',
       'border-r-(length:--glyph-border-width)',
       'transition-[width] duration-(--glyph-duration-base) ease-standard data-[collapsed=true]:w-15',
     ],
@@ -50,10 +52,14 @@ export const sidebarStyles = tv({
       transition,
       focusRing,
       'hover:bg-muted hover:text-foreground',
-      'aria-[current=page]:bg-muted aria-[current=page]:text-foreground',
-      'before:absolute before:inset-y-1.5 before:-left-3 before:w-0.5 before:rounded-r-pill before:bg-transparent aria-[current=page]:before:bg-primary',
+      'aria-[current=page]:text-foreground',
       'group-data-[collapsed=true]/sidebar:justify-center group-data-[collapsed=true]/sidebar:px-0',
     ],
+    /** The active item's background and accent bar. Slides between items on navigation. */
+    itemIndicator: [
+      'pointer-events-none absolute inset-0 -z-10 rounded-[inherit] bg-muted',
+      'before:absolute before:inset-y-1.5 before:-left-3 before:w-0.5 before:rounded-r-pill before:bg-primary',
+    ],
     itemIcon: 'flex size-4 shrink-0 items-center justify-center [&>svg]:size-4',
     itemLabel: 'min-w-0 flex-1 truncate text-left group-data-[collapsed=true]/sidebar:sr-only',
     itemBadge:
@@ -65,7 +71,7 @@ export const sidebarStyles = tv({
   },
 })
 
-export const navbarStyles = tv({
+export const navbarStyles = /* @__PURE__ */ tv({
   slots: {
     root: [
       'top-0 z-40 w-full border-b-transparent',
@@ -83,9 +89,10 @@ export const navbarStyles = tv({
     ],
     actions: 'ml-auto hidden items-center gap-2 md:flex',
     menuButton: 'ml-auto md:hidden',
-    overlay: 'fixed inset-0 z-50 animate-fade-in bg-overlay',
+    overlay:
+      'fixed inset-0 z-50 bg-overlay data-[state=open]:animate-fade-in data-[state=closed]:animate-fade-out',
     panel: [
-      'fixed inset-x-0 top-0 z-50 max-h-dvh overflow-y-auto border-b-border bg-background px-4 pb-6 shadow-lg outline-none animate-slide-in-top',
+      'fixed inset-x-0 top-0 z-50 max-h-dvh overflow-y-auto border-b-border bg-background px-4 pb-6 shadow-lg outline-none animate-slide-in-top data-[state=closed]:animate-pop-out',
       'border-b-(length:--glyph-border-width)',
     ],
     panelHeader: 'flex h-16 items-center justify-between',
@@ -112,7 +119,7 @@ export const navbarStyles = tv({
   defaultVariants: { sticky: true, blur: true },
 })
 
-export const pageHeaderStyles = tv({
+export const pageHeaderStyles = /* @__PURE__ */ tv({
   slots: {
     root: [
       'flex flex-col gap-4 border-b-border pb-5 sm:flex-row sm:items-end sm:justify-between',

package/src/patterns/app-shell/sidebar.tsx

@@ -1,15 +1,26 @@
-import type { ComponentProps, MouseEvent, ReactNode } from 'react'
+import {
+  type ComponentProps,
+  createContext,
+  type MouseEvent,
+  type ReactNode,
+  useContext,
+  useId,
+} from 'react'
 import { IconButton, type IconButtonProps } from '../../components/button'
 import { Tooltip } from '../../components/tooltip'
 import { useComponentConfig } from '../../hooks/use-component-config'
 import { useMediaQuery } from '../../hooks/use-media-query'
 import { PanelLeftIcon } from '../../internal/icons'
+import { ActiveIndicator } from '../../motion/active-indicator'
 import { useIsActive, useLinkComponent } from '../../provider/glyph-context'
 import { sidebarStyles } from './app-shell.styles'
 import { useAppShell } from './app-shell-context'
 
 const s = sidebarStyles()
 
+/** One id per sidebar, so its active highlight slides between that sidebar's items only. */
+const SidebarIndicatorContext = createContext<string | null>(null)
+
 function useSlots() {
   return useComponentConfig('Sidebar', {})[1]
 }
@@ -18,13 +29,16 @@ function useSlots() {
 export function Sidebar({ className, ...props }: ComponentProps<'aside'>) {
   const { collapsed } = useAppShell()
   const slots = useSlots()
+  const indicatorId = `${useId()}-sidebar-indicator`
   return (
-    <aside
-      data-slot="sidebar"
-      data-collapsed={collapsed}
-      className={s.root({ class: [slots.root, className] })}
-      {...props}
-    />
+    <SidebarIndicatorContext.Provider value={indicatorId}>
+      <aside
+        data-slot="sidebar"
+        data-collapsed={collapsed}
+        className={s.root({ class: [slots.root, className] })}
+        {...props}
+      />
+    </SidebarIndicatorContext.Provider>
   )
 }
 
@@ -98,6 +112,7 @@ export function SidebarItem({
   const { collapsed, inDrawer, setMobileOpen } = useAppShell()
   const Link = useLinkComponent()
   const slots = useSlots()
+  const indicatorId = useContext(SidebarIndicatorContext)
 
   const handleClick = (event: MouseEvent<HTMLElement>) => {
     onClick?.(event)
@@ -106,6 +121,12 @@ export function SidebarItem({
 
   const content = (
     <>
+      {active && indicatorId && (
+        <ActiveIndicator
+          layoutId={indicatorId}
+          className={s.itemIndicator({ class: slots.itemIndicator })}
+        />
+      )}
       {icon && (
         <span className={s.itemIcon({ class: slots.itemIcon })} aria-hidden="true">
           {icon}

package/src/patterns/async/states.tsx

@@ -5,7 +5,7 @@ import { useComponentConfig } from '../../hooks/use-component-config'
 import { AlertIcon, InboxIcon } from '../../internal/icons'
 import { tv } from '../../utils/tv'
 
-export const stateStyles = tv({
+export const stateStyles = /* @__PURE__ */ tv({
   slots: {
     root: 'flex flex-col items-center justify-center gap-3 px-6 py-12 text-center',
     icon: 'flex size-10 items-center justify-center rounded-md border border-border bg-surface text-muted-foreground shadow-xs [&>svg]:size-5',