[pull] main from chakra-ui:main

.storybook/modules/swap.module.css

@@ -0,0 +1,152 @@
+.Button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0.5rem;
+  border-radius: 0.375rem;
+  border: 1px solid var(--demo-border-emphasized);
+  background: transparent;
+  color: var(--demo-neutral-fg);
+  font-family: inherit;
+  cursor: pointer;
+
+  & svg {
+    width: 1.25rem;
+    height: 1.25rem;
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--demo-coral-focus-ring);
+    outline-offset: 2px;
+  }
+}
+
+.FadeIndicator {
+  &[data-state='open'] {
+    animation-name: fade-in;
+    animation-duration: 200ms;
+    animation-timing-function: ease-out;
+  }
+
+  &[data-state='closed'] {
+    animation-name: fade-out;
+    animation-duration: 100ms;
+    animation-timing-function: ease-in;
+  }
+}
+
+.FlipIndicator {
+  backface-visibility: hidden;
+
+  &[data-state='open'] {
+    animation-name: flip-in;
+    animation-duration: 400ms;
+    animation-timing-function: ease;
+  }
+
+  &[data-state='closed'] {
+    animation-name: flip-out;
+    animation-duration: 200ms;
+    animation-timing-function: ease;
+  }
+}
+
+.ScaleIndicator {
+  &[data-state='open'] {
+    animation-name: scale-in, fade-in;
+    animation-duration: 200ms;
+    animation-timing-function: ease-out;
+  }
+
+  &[data-state='closed'] {
+    animation-name: scale-out, fade-out;
+    animation-duration: 100ms;
+    animation-timing-function: ease-in;
+  }
+}
+
+.RotateIndicator {
+  &[data-state='open'] {
+    animation-name: rotate-in, fade-in;
+    animation-duration: 250ms;
+    animation-timing-function: ease-out;
+  }
+
+  &[data-state='closed'] {
+    animation-name: rotate-out, fade-out;
+    animation-duration: 100ms;
+    animation-timing-function: ease-in;
+  }
+}
+
+@keyframes fade-in {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes fade-out {
+  from {
+    opacity: 1;
+  }
+  to {
+    opacity: 0;
+  }
+}
+
+@keyframes rotate-in {
+  from {
+    transform: rotate(-90deg);
+  }
+  to {
+    transform: rotate(0deg);
+  }
+}
+
+@keyframes rotate-out {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(90deg);
+  }
+}
+
+@keyframes scale-in {
+  from {
+    transform: scale(0);
+  }
+  to {
+    transform: scale(1);
+  }
+}
+
+@keyframes scale-out {
+  from {
+    transform: scale(1);
+  }
+  to {
+    transform: scale(0);
+  }
+}
+
+@keyframes flip-in {
+  from {
+    transform: rotateY(180deg);
+  }
+  to {
+    transform: rotateY(0deg);
+  }
+}
+
+@keyframes flip-out {
+  from {
+    transform: rotateY(0deg);
+  }
+  to {
+    transform: rotateY(180deg);
+  }
+}

packages/react/CHANGELOG.md

@@ -3,6 +3,8 @@
 ### Added
 
 - **Locale**: Added `useDateFormatter` hook for localized date formatting using `@internationalized/date`
+- **Swap**: Added new `Swap` component for toggling between two visual states with CSS animations using dual presence
+  instances
 
 ## [5.31.0] - 2026-02-04
 

packages/react/src/components/anatomy.ts

@@ -38,6 +38,7 @@ export { signaturePadAnatomy } from './signature-pad/signature-pad.anatomy'
 export { sliderAnatomy } from './slider/slider.anatomy'
 export { splitterAnatomy } from './splitter/splitter.anatomy'
 export { stepsAnatomy } from './steps/steps.anatomy'
+export { swapAnatomy } from './swap/swap.anatomy'
 export { switchAnatomy } from './switch/switch.anatomy'
 export { tabsAnatomy } from './tabs/tabs.anatomy'
 export { tagsInputAnatomy } from './tags-input/tags-input.anatomy'

packages/react/src/components/index.ts

@@ -47,6 +47,7 @@ export * from './signature-pad'
 export * from './slider'
 export * from './splitter'
 export * from './steps'
+export * from './swap'
 export * from './switch'
 export * from './tabs'
 export * from './tags-input'

packages/react/src/components/swap/examples/fade.tsx

@@ -0,0 +1,21 @@
+import { Swap } from '@ark-ui/react/swap'
+import { CheckIcon, XIcon } from 'lucide-react'
+import { useState } from 'react'
+import styles from 'styles/swap.module.css'
+
+export const Fade = () => {
+  const [swapped, setSwapped] = useState(false)
+
+  return (
+    <button type="button" className={styles.Button} onClick={() => setSwapped((prev) => !prev)}>
+      <Swap.Root swap={swapped}>
+        <Swap.Indicator type="on" className={styles.FadeIndicator}>
+          <CheckIcon />
+        </Swap.Indicator>
+        <Swap.Indicator type="off" className={styles.FadeIndicator}>
+          <XIcon />
+        </Swap.Indicator>
+      </Swap.Root>
+    </button>
+  )
+}

packages/react/src/components/swap/examples/flip.tsx

@@ -0,0 +1,21 @@
+import { Swap } from '@ark-ui/react/swap'
+import { PauseIcon, PlayIcon } from 'lucide-react'
+import { useState } from 'react'
+import styles from 'styles/swap.module.css'
+
+export const Flip = () => {
+  const [swapped, setSwapped] = useState(false)
+
+  return (
+    <button type="button" className={styles.Button} onClick={() => setSwapped((prev) => !prev)}>
+      <Swap.Root swap={swapped} style={{ perspective: '200px' }}>
+        <Swap.Indicator type="on" className={styles.FlipIndicator}>
+          <PlayIcon />
+        </Swap.Indicator>
+        <Swap.Indicator type="off" className={styles.FlipIndicator}>
+          <PauseIcon />
+        </Swap.Indicator>
+      </Swap.Root>
+    </button>
+  )
+}

packages/react/src/components/swap/examples/rotate.tsx

@@ -0,0 +1,21 @@
+import { Swap } from '@ark-ui/react/swap'
+import { MoonIcon, SunIcon } from 'lucide-react'
+import { useState } from 'react'
+import styles from 'styles/swap.module.css'
+
+export const Rotate = () => {
+  const [swapped, setSwapped] = useState(false)
+
+  return (
+    <button type="button" className={styles.Button} onClick={() => setSwapped((prev) => !prev)}>
+      <Swap.Root swap={swapped}>
+        <Swap.Indicator type="on" className={styles.RotateIndicator}>
+          <SunIcon />
+        </Swap.Indicator>
+        <Swap.Indicator type="off" className={styles.RotateIndicator}>
+          <MoonIcon />
+        </Swap.Indicator>
+      </Swap.Root>
+    </button>
+  )
+}

packages/react/src/components/swap/examples/scale.tsx

@@ -0,0 +1,21 @@
+import { Swap } from '@ark-ui/react/swap'
+import { Volume2Icon, VolumeXIcon } from 'lucide-react'
+import { useState } from 'react'
+import styles from 'styles/swap.module.css'
+
+export const Scale = () => {
+  const [swapped, setSwapped] = useState(false)
+
+  return (
+    <button type="button" className={styles.Button} onClick={() => setSwapped((prev) => !prev)}>
+      <Swap.Root swap={swapped}>
+        <Swap.Indicator type="on" className={styles.ScaleIndicator}>
+          <Volume2Icon />
+        </Swap.Indicator>
+        <Swap.Indicator type="off" className={styles.ScaleIndicator}>
+          <VolumeXIcon />
+        </Swap.Indicator>
+      </Swap.Root>
+    </button>
+  )
+}

packages/react/src/components/swap/index.ts

@@ -0,0 +1,7 @@
+export * as Swap from './swap'
+export { SwapIndicator, type SwapIndicatorBaseProps, type SwapIndicatorProps } from './swap-indicator'
+export { SwapRoot, type SwapRootBaseProps, type SwapRootProps } from './swap-root'
+export { SwapRootProvider, type SwapRootProviderBaseProps, type SwapRootProviderProps } from './swap-root-provider'
+export { swapAnatomy } from './swap.anatomy'
+export { useSwap, type UseSwapProps, type UseSwapReturn } from './use-swap'
+export { useSwapContext, type UseSwapContext } from './use-swap-context'

packages/react/src/components/swap/swap-indicator.tsx

@@ -0,0 +1,26 @@
+import { mergeProps } from '@zag-js/react'
+import { forwardRef } from 'react'
+import { composeRefs } from '../../utils/compose-refs'
+import type { HTMLProps, PolymorphicProps } from '../factory'
+import { ark } from '../factory'
+import { useSwapContext } from './use-swap-context'
+
+export interface SwapIndicatorBaseProps extends PolymorphicProps {
+  type: 'on' | 'off'
+}
+
+export interface SwapIndicatorProps extends HTMLProps<'span'>, SwapIndicatorBaseProps {}
+
+export const SwapIndicator = forwardRef<HTMLSpanElement, SwapIndicatorProps>((props, ref) => {
+  const { type, ...restProps } = props
+  const swap = useSwapContext()
+  const presence = type === 'on' ? swap.onPresence : swap.offPresence
+
+  if (presence.unmounted) return null
+
+  const mergedProps = mergeProps(swap.getIndicatorProps({ type }), restProps)
+
+  return <ark.span {...mergedProps} ref={composeRefs(presence.ref, ref)} />
+})
+
+SwapIndicator.displayName = 'SwapIndicator'

packages/react/src/components/swap/swap-root-provider.tsx

@@ -0,0 +1,27 @@
+import { mergeProps } from '@zag-js/react'
+import { forwardRef } from 'react'
+import type { HTMLProps, PolymorphicProps } from '../factory'
+import { ark } from '../factory'
+import type { UseSwapReturn } from './use-swap'
+import { SwapProvider } from './use-swap-context'
+
+export interface SwapRootProviderBaseProps extends PolymorphicProps {
+  value: UseSwapReturn
+}
+
+export interface SwapRootProviderProps extends HTMLProps<'span'>, SwapRootProviderBaseProps {}
+
+export const SwapRootProvider = forwardRef<HTMLSpanElement, SwapRootProviderProps>((props, ref) => {
+  const { value, children, ...restProps } = props
+  const mergedProps = mergeProps(value.getRootProps(), restProps)
+
+  return (
+    <SwapProvider value={value}>
+      <ark.span {...mergedProps} ref={ref}>
+        {children}
+      </ark.span>
+    </SwapProvider>
+  )
+})
+
+SwapRootProvider.displayName = 'SwapRootProvider'

packages/react/src/components/swap/swap-root.tsx

@@ -0,0 +1,26 @@
+import { mergeProps } from '@zag-js/react'
+import { forwardRef } from 'react'
+import type { HTMLProps, PolymorphicProps } from '../factory'
+import { ark } from '../factory'
+import { type UseSwapProps, useSwap } from './use-swap'
+import { SwapProvider } from './use-swap-context'
+
+export interface SwapRootBaseProps extends UseSwapProps, PolymorphicProps {}
+
+export interface SwapRootProps extends HTMLProps<'span'>, SwapRootBaseProps {}
+
+export const SwapRoot = forwardRef<HTMLSpanElement, SwapRootProps>((props, ref) => {
+  const { children, swap: swapProp, lazyMount, unmountOnExit, ...restProps } = props
+  const swap = useSwap({ swap: swapProp, lazyMount, unmountOnExit })
+  const mergedProps = mergeProps(swap.getRootProps(), restProps)
+
+  return (
+    <SwapProvider value={swap}>
+      <ark.span {...mergedProps} ref={ref}>
+        {children}
+      </ark.span>
+    </SwapProvider>
+  )
+})
+
+SwapRoot.displayName = 'SwapRoot'

packages/react/src/components/swap/swap.anatomy.ts

@@ -0,0 +1,5 @@
+import { createAnatomy } from '@zag-js/anatomy'
+
+export const swapAnatomy = createAnatomy('swap', ['root', 'indicator'])
+
+export const parts = swapAnatomy.build()

packages/react/src/components/swap/swap.stories.tsx

@@ -0,0 +1,12 @@
+import type { Meta } from '@storybook/react-vite'
+
+const meta: Meta = {
+  title: 'Components / Swap',
+}
+
+export default meta
+
+export { Fade } from './examples/fade'
+export { Flip } from './examples/flip'
+export { Rotate } from './examples/rotate'
+export { Scale } from './examples/scale'

packages/react/src/components/swap/swap.ts

@@ -0,0 +1,12 @@
+export {
+  SwapIndicator as Indicator,
+  type SwapIndicatorBaseProps as IndicatorBaseProps,
+  type SwapIndicatorProps as IndicatorProps,
+} from './swap-indicator'
+export { SwapRoot as Root, type SwapRootBaseProps as RootBaseProps, type SwapRootProps as RootProps } from './swap-root'
+export {
+  SwapRootProvider as RootProvider,
+  type SwapRootProviderBaseProps as RootProviderBaseProps,
+  type SwapRootProviderProps as RootProviderProps,
+} from './swap-root-provider'
+export { swapAnatomy } from './swap.anatomy'

packages/react/src/components/swap/use-swap-context.ts

@@ -0,0 +1,10 @@
+import { createContext } from '../../utils/create-context'
+import type { UseSwapReturn } from './use-swap'
+
+export interface UseSwapContext extends UseSwapReturn {}
+
+export const [SwapProvider, useSwapContext] = createContext<UseSwapContext>({
+  name: 'SwapContext',
+  hookName: 'useSwapContext',
+  providerName: '<SwapProvider />',
+})