@edgeandnode/eds-react 1.0.1 → 1.1.0

package/src/EDSProvider.tsx

@@ -1,32 +1,38 @@
 'use client'
 
-import { useCallback, useLayoutEffect, useMemo, useRef, useState, type ComponentProps } from 'react'
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useSyncExternalStore,
+  type ComponentProps,
+} from 'react'
 import { mergeProps } from '@base-ui/react'
 import { DirectionProvider } from '@base-ui/react/direction-provider'
 import { Tooltip } from '@base-ui/react/tooltip'
 
 import { ButtonOrLink, type ButtonOrLinkConfigProps } from './components/base/ButtonOrLink.tsx'
 import { Pane } from './components/Pane.tsx'
-import { EDSContext, type ResolvedTheme, type Theme, type ThemePersistence } from './EDSContext.ts'
+import {
+  EDSContext,
+  THEME_CLASSES,
+  type ResolvedTheme,
+  type Theme,
+  type ThemePersistence,
+} from './EDSContext.ts'
 import { useControlled } from './hooks/useControlled.ts'
 import { useIsHydrated } from './hooks/useIsHydrated.ts'
+import {
+  COOKIE_REGEX,
+  isValidTheme,
+  parseThemeCookie,
+  PERSISTENCE_KEY,
+  VALID_THEMES,
+} from './theme-persistence.ts'
 import { cn } from './utils/index.ts'
 
-const PERSISTENCE_KEY = 'eds-active-theme'
-const COOKIE_REGEX = new RegExp(`(?:^|; )${PERSISTENCE_KEY}=([^;]+)`)
-
-const THEME_CLASSES: Record<Theme, string> = {
-  dark: 'eds-dark',
-  light: 'eds-light',
-  system: 'eds-system',
-}
-
-const VALID_THEMES: readonly Theme[] = ['dark', 'light', 'system']
-
-function isValidTheme(value: unknown): value is Theme {
-  return typeof value === 'string' && (VALID_THEMES as readonly string[]).includes(value)
-}
-
 interface PersistenceAdapter {
   get: () => Theme | null
   set: (value: Theme) => void
@@ -59,17 +65,14 @@ function resolvePersistence(persistTheme: ThemePersistence | undefined): Persist
     return {
       get: () => {
         try {
-          const match = document.cookie.match(COOKIE_REGEX)
-          if (match === null) return null
-          const value = decodeURIComponent(match[1] as string)
-          return isValidTheme(value) ? value : null
+          return parseThemeCookie(document.cookie) ?? null
         } catch {
           return null
         }
       },
       set: (value) => {
         try {
-          document.cookie = `${PERSISTENCE_KEY}=${encodeURIComponent(value)}; path=/; max-age=31536000; samesite=lax`
+          document.cookie = `${PERSISTENCE_KEY}=${value}; path=/; max-age=31536000; samesite=lax`
         } catch {
           // ignore restrictive environments
         }
@@ -99,12 +102,13 @@ function resolvePersistence(persistTheme: ThemePersistence | undefined): Persist
 const prefersDarkMediaQuery =
   typeof window !== 'undefined' ? window.matchMedia('(prefers-color-scheme: dark)') : null
 
-function resolveTheme(theme: Theme, systemFallback: ResolvedTheme = 'dark'): ResolvedTheme {
-  if (theme === 'system') {
-    if (prefersDarkMediaQuery === null) return systemFallback
-    return prefersDarkMediaQuery.matches ? 'dark' : 'light'
-  }
-  return theme
+function subscribeToSystemTheme(onChange: () => void) {
+  prefersDarkMediaQuery?.addEventListener('change', onChange)
+  return () => prefersDarkMediaQuery?.removeEventListener('change', onChange)
+}
+
+function getSystemTheme(): ResolvedTheme {
+  return prefersDarkMediaQuery?.matches === false ? 'light' : 'dark'
 }
 
 export interface EDSProviderProps extends Omit<ComponentProps<'div'>, 'dir'> {
@@ -130,16 +134,22 @@ export interface EDSProviderProps extends Omit<ComponentProps<'div'>, 'dir'> {
    * - `'localStorage'`: reads/writes `localStorage['eds-active-theme']`. Inline pre-hydration script
    *   reads the value before first paint — no SSR flash.
    * - `'cookie'`: reads/writes a `eds-active-theme` cookie (`path=/; max-age=31536000;
-   *   samesite=lax`). Same no-flash SSR; also readable server-side (e.g. via Next.js `headers()`).
+   *   samesite=lax`). Same no-flash SSR; pass `getThemeFromCookies()` to `defaultTheme` on the
+   *   server so it renders the saved theme too.
    * - `{ get, set }`: custom adapter (different key, encryption, remote storage, etc.). Invalid
-   *   values from `get()` fall back to `defaultTheme`. No pre-hydration script is emitted; for
-   *   zero-flash SSR, inject your own inline script that adds the matching `eds-*` class to
-   *   `<html>` before paint.
+   *   values from `get()` fall back to `defaultTheme`. In uncontrolled mode, no pre-hydration
+   *   script is emitted; for zero-flash SSR, inject your own inline script that adds the matching
+   *   `eds-*` class to `<html>` before paint.
    *
    * The two string presets share the key `'eds-active-theme'` — use a custom adapter for per-app
    * isolation on the same origin.
    */
   persistTheme?: ThemePersistence | undefined
+  /**
+   * Nonce for the inline scripts and styles `EDSProvider` adds, if your Content Security Policy
+   * requires one.
+   */
+  nonce?: string | undefined
   /** @default 'ltr' */
   direction?: ComponentProps<typeof DirectionProvider>['direction'] | undefined
   /** @default 'en' // or for `direction="rtl"`, 'ar' */
@@ -153,7 +163,8 @@ export type { EDSContextValue, ResolvedTheme, Theme, ThemePersistence } from './
  * Provides global configuration and enhancements for EDS components.
  *
  * Note: Only one EDSProvider should be used per app, typically at the root. If you need different
- * themes for different parts of the app, use the `eds-dark` / `eds-light` utility classes instead.
+ * themes for different parts of the app, use the `Dark`, `Light`, and `LocalTheme` components
+ * instead.
  *
  * **Next.js App Router:** add `suppressHydrationWarning` to your `<html>` tag in `app/layout.tsx`.
  * The pre-hydration script applies the theme class to `<html>` before React hydrates (preventing a
@@ -192,6 +203,7 @@ export function EDSProvider({
   defaultTheme = 'dark',
   onThemeChange,
   persistTheme,
+  nonce,
   direction = 'ltr',
   language = direction === 'rtl' ? 'ar' : 'en',
   buttonOrLinkConfig,
@@ -280,6 +292,7 @@ export function EDSProvider({
     }
 
     const style = document.createElement('style')
+    if (nonce !== undefined) style.nonce = nonce
     style.textContent = '*:not(.eds-segmented-control *) { transition: none !important; }'
     document.head.appendChild(style)
     removeClasses()
@@ -293,30 +306,15 @@ export function EDSProvider({
       style.remove()
       removeClasses()
     }
-  }, [theme])
+  }, [theme, nonce])
 
-  // `activeTheme` resolves `'system'` to `'dark'` or `'light'` via `prefers-color-scheme`. Initial
-  // state skips `matchMedia` to keep SSR and first client render in sync; the effect catches up
-  // pre-paint.
-  const systemFallback: ResolvedTheme = defaultTheme === 'system' ? 'dark' : defaultTheme
-
-  const [activeTheme, setActiveTheme] = useState<ResolvedTheme>(() =>
-    theme === 'system' ? systemFallback : theme,
+  // The server can't know the OS preference, so it renders `'dark'`, `:root`'s default
+  const systemTheme = useSyncExternalStore<ResolvedTheme>(
+    subscribeToSystemTheme,
+    getSystemTheme,
+    () => 'dark',
   )
 
-  useLayoutEffect(() => {
-    setActiveTheme(resolveTheme(theme, systemFallback))
-
-    if (theme !== 'system') return
-
-    const handleChange = (event: MediaQueryListEvent) => {
-      setActiveTheme(event.matches ? 'dark' : 'light')
-    }
-
-    prefersDarkMediaQuery?.addEventListener('change', handleChange)
-    return () => prefersDarkMediaQuery?.removeEventListener('change', handleChange)
-  }, [theme, systemFallback])
-
   /**
    * Add the `data-eds-active` attribute to the `html` element when the Space key is pressed to
    * improve Tailwind's `active` state.
@@ -370,15 +368,34 @@ export function EDSProvider({
     }
   }, [])
 
+  /**
+   * Warn if build tools transpiled `light-dark()` (e.g. Lightning CSS with older browser targets).
+   * Its fallback resolves tokens on `:root`, so components inside `Dark` and `Light` would get the
+   * page's colors.
+   */
+  useEffect(() => {
+    const lightDarkTest = getComputedStyle(document.documentElement).getPropertyValue(
+      '--eds-light-dark-test',
+    )
+    if (lightDarkTest !== '' && !lightDarkTest.includes('light-dark')) {
+      // oxlint-disable-next-line no-console
+      console.warn(
+        "[EDSProvider] `light-dark()` was transpiled by your build tools, so components inside `Dark`, `Light`, and `LocalTheme` will use the page's colors. Target Chrome 123, Safari 17.5, and Firefox 120 or newer (see the `@edgeandnode/eds-react` README).",
+      )
+    }
+  }, [])
+
+  const isHydrated = useIsHydrated()
+
   const edsContextValue = useMemo(
     () => ({
       theme,
-      activeTheme,
       setTheme,
+      systemTheme,
       direction,
       language,
     }),
-    [theme, activeTheme, setTheme, direction, language],
+    [theme, setTheme, systemTheme, direction, language],
   )
 
   return (
@@ -387,10 +404,19 @@ export function EDSProvider({
         <Pane.Provider>
           <Tooltip.Provider timeout={300}>
             <ButtonOrLink.Config {...buttonOrLinkConfig}>
-              {/* Set the theme class on <html> before first paint to prevent a flash */}
-              <PreHydrationScript>
-                {buildThemeScript(controlledTheme, defaultTheme, persistTheme)}
-              </PreHydrationScript>
+              {/**
+               * Apply the theme before first paint to prevent a flash, as the browser runs this script and
+               * applies this style while parsing the server-rendered HTML. The style applies a light or system
+               * theme until a theme class is set on `<html>`, in case there's no script (with a custom
+               * `persistTheme` adapter) or it can't run (e.g. blocked by a Content Security Policy). Both are
+               * removed after hydration.
+               */}
+              {isHydrated ? null : (
+                <>
+                  {renderThemeScript(controlledTheme, defaultTheme, persistTheme, nonce)}
+                  {renderThemeStyle(controlledTheme ?? defaultTheme, nonce)}
+                </>
+              )}
               <div
                 dir={direction}
                 lang={language}
@@ -406,38 +432,43 @@ export function EDSProvider({
   )
 }
 
-function buildThemeScript(
+function renderThemeScript(
   controlledTheme: Theme | undefined,
   defaultTheme: Theme,
   persistTheme: ThemePersistence | undefined,
+  nonce: string | undefined,
 ) {
-  // Controlled mode and the `undefined` / custom-adapter cases use the known theme — only the
-  // string presets need a storage lookup.
-  if (controlledTheme !== undefined) {
-    return `document.documentElement.classList.add('eds-${controlledTheme}')`
-  }
-  if (persistTheme !== 'localStorage' && persistTheme !== 'cookie') {
-    return `document.documentElement.classList.add('eds-${defaultTheme}')`
+  if (controlledTheme !== undefined || persistTheme === undefined) {
+    const script = `document.documentElement.classList.add('eds-${controlledTheme ?? defaultTheme}')`
+    return <script nonce={nonce}>{script}</script>
   }
+  // Custom adapters need the app's own script (see `persistTheme`), which this would conflict with
+  if (persistTheme !== 'localStorage' && persistTheme !== 'cookie') return null
 
-  const invalidCheck = VALID_THEMES.map((t) => `t!=='${t}'`).join('&&')
+  const invalidCheck = VALID_THEMES.map((theme) => `t!=='${theme}'`).join('&&')
   const readExpression =
     persistTheme === 'localStorage'
       ? `localStorage.getItem('${PERSISTENCE_KEY}')`
-      : `decodeURIComponent((document.cookie.match(/(?:^|; )${PERSISTENCE_KEY}=([^;]+)/)||[])[1]||'')`
-  return `(function(){try{var t=${readExpression};if(${invalidCheck})t='${defaultTheme}';document.documentElement.classList.add('eds-'+t)}catch(e){document.documentElement.classList.add('eds-${defaultTheme}')}})()`
+      : `(document.cookie.match(${COOKIE_REGEX})||[])[1]`
+  const script = `(function(){try{var t=${readExpression};if(${invalidCheck})t='${defaultTheme}';document.documentElement.classList.add('eds-'+t)}catch(e){document.documentElement.classList.add('eds-${defaultTheme}')}})()`
+  return <script nonce={nonce}>{script}</script>
 }
 
-interface PreHydrationScriptProps extends ComponentProps<'script'> {}
+const ROOT_WITHOUT_THEME_CLASS = `:root:not(${Object.values(THEME_CLASSES)
+  .map((themeClass) => `.${themeClass}`)
+  .join(', ')})`
 
 /**
- * Renders a `<script>` element that exists only until React hydration completes.
- *
- * Outputs its tag during SSR and during the client's initial render (ensuring the markup matches),
- * and removes itself after hydration to keep the DOM clean. The browser executes the inline script
- * as it parses the HTML, before React hydrates and before any styled body content paints.
+ * `:root` is dark by default, so other themes need a style until the theme class is set on
+ * `<html>`.
  */
-function PreHydrationScript({ children, ...props }: PreHydrationScriptProps) {
-  if (useIsHydrated()) return null
-  return <script {...props}>{children}</script>
+const THEME_STYLES: Record<Theme, string | null> = {
+  dark: null,
+  light: `${ROOT_WITHOUT_THEME_CLASS}{color-scheme:only light;--eds-color-scheme:light}`,
+  system: `${ROOT_WITHOUT_THEME_CLASS}{color-scheme:light dark}@media (prefers-color-scheme:light){${ROOT_WITHOUT_THEME_CLASS}{--eds-color-scheme:light}}`,
+}
+
+function renderThemeStyle(theme: Theme, nonce: string | undefined) {
+  const style = THEME_STYLES[theme]
+  return style !== null ? <style nonce={nonce}>{style}</style> : null
 }

package/src/components/Address.tsx

@@ -26,14 +26,15 @@ export declare namespace AddressProps {
   interface ButtonProps
     extends
       CommonProps,
-      MaybeButtonOrLinkProps.ButtonProps,
+      Omit<MaybeButtonOrLinkProps.ButtonProps, 'as'>,
       MaybeButtonOrLinkProps.DisableableProps {}
   interface LinkProps
     extends
       CommonProps,
-      MaybeButtonOrLinkProps.LinkProps,
+      Omit<MaybeButtonOrLinkProps.LinkProps, 'as'>,
       MaybeButtonOrLinkProps.DisableableProps {}
-  interface OtherElementProps extends CommonProps, MaybeButtonOrLinkProps.OtherElementProps {}
+  interface OtherElementProps
+    extends CommonProps, Omit<MaybeButtonOrLinkProps.OtherElementProps, 'as'> {}
 }
 
 export type AddressProps =

package/src/components/Avatar.tsx

@@ -9,7 +9,8 @@ import avatarPlaceholderRounded from '@edgeandnode/eds-react/assets/avatar-place
 import { createIdenticon, PLACEHOLDER_ADDRESS } from '@edgeandnode/eds-utils'
 
 import { useCSSPropsPolyfill, useEDS } from '../hooks/index.ts'
-import { cn, getAssetUrl, getCSSPropsAttributes, isReactNode } from '../utils/index.ts'
+import { cn, getAssetUrl, getCSSPropsAttributes } from '../utils/index.ts'
+import { getTooltipProps } from '../utils/internal/index.ts'
 import { AvatarMeta } from './Avatar.meta.ts'
 import { MaybeButtonOrLink, type MaybeButtonOrLinkProps } from './base/MaybeButtonOrLink.tsx'
 import { Tooltip, type TooltipProps } from './Tooltip.tsx'
@@ -35,10 +36,14 @@ export declare namespace AvatarProps {
     tooltip?: TooltipProps['content'] | Omit<TooltipProps, 'children'> | undefined
   }
   interface CommonProps extends OwnProps, EDSComponentProps<typeof AvatarMeta> {}
-  interface ButtonProps extends CommonProps, Omit<MaybeButtonOrLinkProps.ButtonProps, 'children'> {}
-  interface LinkProps extends CommonProps, Omit<MaybeButtonOrLinkProps.LinkProps, 'children'> {}
+  interface ButtonProps
+    extends CommonProps, Omit<MaybeButtonOrLinkProps.ButtonProps, 'as' | 'children' | 'render'> {}
+  interface LinkProps
+    extends CommonProps, Omit<MaybeButtonOrLinkProps.LinkProps, 'as' | 'children' | 'render'> {}
   interface OtherElementProps
-    extends CommonProps, Omit<MaybeButtonOrLinkProps.OtherElementProps, 'children'> {}
+    extends
+      CommonProps,
+      Omit<MaybeButtonOrLinkProps.OtherElementProps, 'as' | 'children' | 'render'> {}
 }
 
 export type AvatarProps =
@@ -94,7 +99,7 @@ export function Avatar({
         return (
           <Tooltip
             content={category !== 'other' ? alt : undefined}
-            {...(isReactNode(tooltip) && tooltip !== undefined ? { content: tooltip } : tooltip)}
+            {...getTooltipProps(tooltip)}
             triggerProps={renderProps}
           >
             <Element {...elementProps}>

package/src/components/Breadcrumbs.parts.tsx

@@ -1,15 +1,15 @@
 'use client'
 
 import {
-  cloneElement,
+  createContext,
   isValidElement,
   useCallback,
+  useContext,
   useMemo,
   useRef,
   useState,
   type ComponentProps,
   type CSSProperties,
-  type ReactElement,
 } from 'react'
 import { mergeProps } from '@base-ui/react'
 import { useRenderCount, useThrottledEffect } from '@react-hookz/web'
@@ -21,12 +21,20 @@ import { ArrowLeftInteractiveIcon, DotsThreeIcon } from '@edgeandnode/eds-react/
 
 import { useCSSPropsPolyfill, useCSSState, useEDS } from '../hooks/index.ts'
 import { cn, getCSSPropsAttributes, splitProps } from '../utils/index.ts'
+import { resolveLazy } from '../utils/internal/index.ts'
 import { renderAddon, type AddonValue } from './base/Addon.tsx'
 import { MaybeButtonOrLink, type MaybeButtonOrLinkProps } from './base/MaybeButtonOrLink.tsx'
 import { BreadcrumbsItemMeta, BreadcrumbsMeta } from './Breadcrumbs.meta.ts'
 import { Button } from './Button.tsx'
 import { Menu } from './Menu.tsx'
 
+/**
+ * Whether a `Breadcrumbs.Item` is (in) the last item of `Breadcrumbs`, which makes it default to
+ * `current`. Provided through context rather than by cloning the item, so that it also works when
+ * items are wrapped in another component.
+ */
+const BreadcrumbsLastItemContext = createContext(false)
+
 export interface BreadcrumbsProps
   extends ComponentProps<'nav'>, EDSComponentProps<typeof BreadcrumbsMeta> {}
 
@@ -47,18 +55,23 @@ export function BreadcrumbsRoot({
 
   const ariaLabel = passedAriaLabel !== undefined ? passedAriaLabel : 'Breadcrumbs'
 
-  // If the last `Breadcrumbs.Item` child doesn't explicitly set `current`, clone it to default
-  // `current` to `true`.
   const processedChildren = useMemo(() => {
     const flatChildren = flattenChildren(children)
-    for (let index = flatChildren.length - 1; index >= 0; index--) {
-      const child = flatChildren[index]
-      if (!isValidElement(child) || child.type !== BreadcrumbsItem) continue
-      const element = child as ReactElement<BreadcrumbsItemProps>
-      if (element.props.current !== undefined) return flatChildren
-      return flatChildren.with(index, cloneElement(element, { current: true }))
-    }
-    return flatChildren
+    const lastItemIndex = flatChildren.findLastIndex(
+      (child) => isValidElement(child) && resolveLazy(child.type) === BreadcrumbsItem,
+    )
+    // If items are wrapped in another component, the last element renders the last item
+    const lastIndex =
+      lastItemIndex !== -1 ? lastItemIndex : flatChildren.findLastIndex(isValidElement)
+    return flatChildren.map((child, index) =>
+      isValidElement(child) ? (
+        <BreadcrumbsLastItemContext.Provider key={child.key} value={index === lastIndex}>
+          {child}
+        </BreadcrumbsLastItemContext.Provider>
+      ) : (
+        child
+      ),
+    )
   }, [children])
 
   const hiddenContainerRef = useRef<HTMLDivElement>(null)
@@ -249,15 +262,17 @@ export declare namespace BreadcrumbsItemProps {
     addonBefore?: AddonValue | undefined
     /**
      * Whether this breadcrumb item represents the current page. Defaults to `true` for the last
-     * `Breadcrumbs.Item` child of `Breadcrumbs`, and `false` for any other item. Set explicitly to
-     * override the default.
+     * `Breadcrumbs.Item` child of `Breadcrumbs` (or the item rendered by its last child, if items
+     * are wrapped in another component), and `false` for any other item. Set explicitly to override
+     * the default.
      */
     current?: boolean | undefined
   }
   interface CommonProps extends OwnProps, EDSComponentProps<typeof BreadcrumbsItemMeta> {}
-  interface ButtonProps extends CommonProps, MaybeButtonOrLinkProps.ButtonProps {}
-  interface LinkProps extends CommonProps, MaybeButtonOrLinkProps.LinkProps {}
-  interface OtherElementProps extends CommonProps, MaybeButtonOrLinkProps.OtherElementProps {}
+  interface ButtonProps extends CommonProps, Omit<MaybeButtonOrLinkProps.ButtonProps, 'as'> {}
+  interface LinkProps extends CommonProps, Omit<MaybeButtonOrLinkProps.LinkProps, 'as'> {}
+  interface OtherElementProps
+    extends CommonProps, Omit<MaybeButtonOrLinkProps.OtherElementProps, 'as'> {}
 }
 
 export type BreadcrumbsItemProps =
@@ -267,11 +282,13 @@ export type BreadcrumbsItemProps =
 
 export function BreadcrumbsItem({
   addonBefore,
-  current = false,
+  current: passedCurrent,
   hideLabel,
   children,
   ...props
 }: BreadcrumbsItemProps) {
+  const isLastItem = useContext(BreadcrumbsLastItemContext)
+  const current = passedCurrent ?? isLastItem
   const { rootProps, nestedProps } = splitProps(props)
 
   const [stateRef, state] = useCSSState({

package/src/components/Button.tsx

@@ -7,7 +7,8 @@ import type { EDSComponentProps } from '@edgeandnode/eds-css'
 import { LoadingIcon } from '@edgeandnode/eds-react/icons'
 
 import { useCSSPropsPolyfill, useCSSState, useEDS } from '../hooks/index.ts'
-import { cn, getCSSPropsAttributes, isReactNode } from '../utils/index.ts'
+import { cn, getCSSPropsAttributes } from '../utils/index.ts'
+import { getTooltipProps } from '../utils/internal/index.ts'
 import { renderAddon, type AddonValue } from './base/Addon.tsx'
 import { ButtonOrLink, type ButtonOrLinkProps } from './base/ButtonOrLink.tsx'
 import { ButtonMeta } from './Button.meta.ts'
@@ -132,7 +133,7 @@ export function Button({
       render={(renderProps, { Element, elementProps }) => (
         <Tooltip
           closeOnClick={typeof props.checked === 'boolean' ? false : undefined} // If this is a toggle button, keep the tooltip open on click by default
-          {...(isReactNode(tooltip) && tooltip !== undefined ? { content: tooltip } : tooltip)}
+          {...getTooltipProps(tooltip)}
           triggerProps={renderProps}
         >
           <Element {...elementProps}>
@@ -167,6 +168,10 @@ export function Button({
                 u:*:transition-opacity
                 u:*:@state-disabled/button:opacity-disabled
                 u:*:@state-disabled/button:grayscale
+                u:*:@prop-variant-inverse/button:scheme-only-dark
+                u:*:@prop-variant-inverse/button:dark:scheme-only-light
+                u:*:@prop-variant-primary/button:scheme-only-dark
+                u:*:@prop-variant-danger/button:scheme-only-dark
                 u:@prop-size-xsmall/button:addon-small
                 u:@prop-size-small/button:addon-small
                 u:@prop-size-medium/button:addon-medium

package/src/components/Card.tsx

@@ -1,7 +1,8 @@
 'use client'
 
-import { useId, type ReactNode } from 'react'
+import { useId, type ElementType, type ReactNode, type Ref } from 'react'
 import { mergeProps } from '@base-ui/react'
+import type { DistributedOmit } from 'type-fest'
 
 import type { EDSComponentProps } from '@edgeandnode/eds-css'
 import { ArrowUpRightInteractiveIcon } from '@edgeandnode/eds-react/icons'
@@ -32,20 +33,24 @@ export declare namespace CardProps {
      */
     autoIcon?: boolean | undefined
   }
+  interface CommonProps extends EDSComponentProps<typeof CardMeta> {
+    /** Attached to the card's outer element, even when the card is a button or link. */
+    ref?: Ref<HTMLElement> | undefined
+  }
   interface ButtonProps
     extends
-      EDSComponentProps<typeof CardMeta>,
+      CommonProps,
       ClickableProps,
-      MaybeButtonOrLinkProps.ButtonProps,
+      Omit<MaybeButtonOrLinkProps.ButtonProps, 'ref' | 'render'>,
       MaybeButtonOrLinkProps.DisableableProps {}
   interface LinkProps
     extends
-      EDSComponentProps<typeof CardMeta>,
+      CommonProps,
       ClickableProps,
-      MaybeButtonOrLinkProps.LinkProps,
+      Omit<MaybeButtonOrLinkProps.LinkProps, 'ref' | 'render'>,
       MaybeButtonOrLinkProps.DisableableProps {}
   interface OtherElementProps
-    extends EDSComponentProps<typeof CardMeta>, MaybeButtonOrLinkProps.OtherElementProps {}
+    extends CommonProps, Omit<MaybeButtonOrLinkProps.OtherElementProps, 'ref' | 'render'> {}
 }
 
 export type CardProps = CardProps.ButtonProps | CardProps.LinkProps | CardProps.OtherElementProps
@@ -57,7 +62,7 @@ export function Card({ ref: passedRef, as, variant, disabled, children, ...props
     interactiveContent = false,
     autoIcon = true,
     ...remainingProps
-  } = props as CardProps.ButtonProps | CardProps.LinkProps
+  } = props as DistributedOmit<CardProps.ButtonProps | CardProps.LinkProps, 'ref'>
   const { rootProps, nestedProps } = splitProps(remainingProps)
 
   const [statePassedRef, state] = useCSSState(
@@ -75,7 +80,8 @@ export function Card({ ref: passedRef, as, variant, disabled, children, ...props
     { ref: statePassedRef },
   )
 
-  const Element = as ?? 'div'
+  // The union of every HTML tag name is too complex a type for JSX
+  const Element = (as ?? 'div') as ElementType
   const uniqueId = useId()
 
   return (

package/src/components/Cluster.tsx

@@ -11,11 +11,13 @@ import { ClusterMeta } from './Cluster.meta.ts'
 
 export declare namespace ClusterProps {
   interface ButtonProps
-    extends EDSComponentProps<typeof ClusterMeta>, MaybeButtonOrLinkProps.ButtonProps {}
+    extends EDSComponentProps<typeof ClusterMeta>, Omit<MaybeButtonOrLinkProps.ButtonProps, 'as'> {}
   interface LinkProps
-    extends EDSComponentProps<typeof ClusterMeta>, MaybeButtonOrLinkProps.LinkProps {}
+    extends EDSComponentProps<typeof ClusterMeta>, Omit<MaybeButtonOrLinkProps.LinkProps, 'as'> {}
   interface OtherElementProps
-    extends EDSComponentProps<typeof ClusterMeta>, MaybeButtonOrLinkProps.OtherElementProps {}
+    extends
+      EDSComponentProps<typeof ClusterMeta>,
+      Omit<MaybeButtonOrLinkProps.OtherElementProps, 'as'> {}
 }
 
 export type ClusterProps =