@edgeandnode/eds-react 1.0.2 → 1.1.1

package/src/EDSProvider.tsx

@@ -6,7 +6,7 @@ import {
   useLayoutEffect,
   useMemo,
   useRef,
-  useState,
+  useSyncExternalStore,
   type ComponentProps,
 } from 'react'
 import { mergeProps } from '@base-ui/react'
@@ -24,17 +24,15 @@ import {
 } 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 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
@@ -67,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
         }
@@ -107,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'> {
@@ -138,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' */
@@ -161,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 `Dark` and `Light` components 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
@@ -200,6 +203,7 @@ export function EDSProvider({
   defaultTheme = 'dark',
   onThemeChange,
   persistTheme,
+  nonce,
   direction = 'ltr',
   language = direction === 'rtl' ? 'ar' : 'en',
   buttonOrLinkConfig,
@@ -288,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()
@@ -301,30 +306,15 @@ export function EDSProvider({
       style.remove()
       removeClasses()
     }
-  }, [theme])
-
-  // `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
+  }, [theme, nonce])
 
-  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.
@@ -390,20 +380,22 @@ export function EDSProvider({
     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` and `Light` will use the page's colors. Target Chrome 123, Safari 17.5, and Firefox 120 or newer (see the `@edgeandnode/eds-react` README).",
+        "[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 (
@@ -412,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}
@@ -431,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/Avatar.tsx

@@ -36,10 +36,12 @@ 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, 'children' | 'render'> {}
+  interface LinkProps
+    extends CommonProps, Omit<MaybeButtonOrLinkProps.LinkProps, 'children' | 'render'> {}
   interface OtherElementProps
-    extends CommonProps, Omit<MaybeButtonOrLinkProps.OtherElementProps, 'children'> {}
+    extends CommonProps, Omit<MaybeButtonOrLinkProps.OtherElementProps, 'children' | 'render'> {}
 }
 
 export type AvatarProps =

package/src/components/Button.tsx

@@ -168,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/Keyboard.tsx

@@ -54,7 +54,7 @@ export function Keyboard({ ref: passedRef, size, children, ...props }: KeyboardP
     >
       <span
         className={cn(
-          `inline-flex h-(--height) min-w-(--height) items-center justify-center rounded-4 border border-default
+          `inline-flex h-(--height) min-w-(--height) items-center justify-center rounded-4 border border-current/15
           @prop-size-small/keyboard:gap-0.5
           @prop-size-small/keyboard:px-0.75
           @prop-size-small/keyboard:text-10

package/src/components/LocalTheme.tsx

@@ -1,39 +1,47 @@
 'use client'
 
-import type { ComponentProps, ElementType } from 'react'
 import { mergeProps } from '@base-ui/react'
+import type { DistributedOmit } from 'type-fest'
 
 import { LocalThemeContext, THEME_CLASSES, type ResolvedTheme } from '../EDSContext.ts'
+import { Render, type AsOrRenderProps, type HTMLElementProps } from './base/Render.tsx'
 
-export interface LocalThemeProps extends ComponentProps<'div'> {
-  /** @default 'div' */
-  as?: ElementType | undefined
+export declare namespace LocalThemeProps {
+  interface CommonProps extends HTMLElementProps {
+    /** The theme to render the content in. */
+    theme: ResolvedTheme
+  }
 }
 
-function LocalTheme({
-  theme,
-  as: Element = 'div',
-  ...props
-}: LocalThemeProps & { theme: ResolvedTheme }) {
+export type LocalThemeProps = LocalThemeProps.CommonProps & AsOrRenderProps
+export type DarkProps = DistributedOmit<LocalThemeProps, 'theme'>
+export type LightProps = DistributedOmit<LocalThemeProps, 'theme'>
+
+/**
+ * Renders its content in the given theme, whatever the page's theme is. Unlike switching between
+ * `Dark` and `Light`, changing `theme` doesn't remount the content. Components that need to know
+ * the theme in JavaScript can read it with `useEDS().activeTheme`.
+ */
+export function LocalTheme({ theme, ...props }: LocalThemeProps) {
   return (
     <LocalThemeContext.Provider value={theme}>
-      <Element {...mergeProps({ className: THEME_CLASSES[theme] }, props)} />
+      <Render {...mergeProps({ className: THEME_CLASSES[theme] }, props)} />
     </LocalThemeContext.Provider>
   )
 }
 
 /**
  * Renders its content in the dark theme, whatever the page's theme is. Components that need to know
- * the theme in JavaScript can read it with `useEDS().localTheme`.
+ * the theme in JavaScript can read it with `useEDS().activeTheme`.
  */
-export function Dark(props: LocalThemeProps) {
+export function Dark(props: DarkProps) {
   return <LocalTheme theme="dark" {...props} />
 }
 
 /**
  * Renders its content in the light theme, whatever the page's theme is. Components that need to
- * know the theme in JavaScript can read it with `useEDS().localTheme`.
+ * know the theme in JavaScript can read it with `useEDS().activeTheme`.
  */
-export function Light(props: LocalThemeProps) {
+export function Light(props: LightProps) {
   return <LocalTheme theme="light" {...props} />
 }