@edgeandnode/eds-react 1.0.1 → 1.1.0

package/src/components/base/Render.tsx

@@ -30,22 +30,46 @@ export type RenderProp<State extends RenderFnState = undefined, ElementProps = u
   | ReactElement<ElementProps>
   | RenderFn<State, ElementProps>
 
-export interface RenderProps<State extends RenderFnState = undefined> {
-  render: RenderProp<State>
+/**
+ * Props of a generic HTML element, for components whose element can be changed with `as` or
+ * `render`.
+ */
+export interface HTMLElementProps extends HTMLProps<HTMLElement> {}
+
+/**
+ * Props to change the element a component renders: a tag name with `as`, or an element or render
+ * function with `render`, which is also how to pass props specific to that element (e.g.
+ * `render={<a href="/" />}`).
+ */
+export type AsOrRenderProps<State extends RenderFnState = undefined> =
+  | {
+      /** Tag name of the element to render. */
+      as?: keyof HTMLElementTagNameMap | undefined
+      render?: undefined
+    }
+  | {
+      as?: undefined
+      /** Element or render function to render instead of the default element. */
+      render?: RenderProp<State> | undefined
+    }
+
+export type RenderProps<State extends RenderFnState = undefined> = AsOrRenderProps<State> & {
   state?: State | undefined
   [key: string]: unknown
 }
 
 /**
- * A utility component that provides polymorphic rendering capabilities. It can render as any HTML
- * element or React component.
+ * A utility component that provides polymorphic rendering capabilities. It renders a `div` by
+ * default, the tag name passed in `as`, or the element or render function passed in `render`.
  */
 export function Render<State extends RenderFnState>({
+  as,
   render,
   state,
   ...props
 }: RenderProps<State>) {
   return useRender({
+    defaultTagName: as,
     render,
     state: state !== undefined ? state : undefined,
     props,

package/src/components/base/index.ts

@@ -25,6 +25,8 @@ export { Portal } from './Portal.tsx'
 export { Presence, usePresence, type PresenceProps } from './Presence.tsx'
 export {
   Render,
+  type AsOrRenderProps,
+  type HTMLElementProps,
   type RenderFnProps,
   type RenderFnState,
   type RenderFn,

package/src/components/index.ts

@@ -44,6 +44,14 @@ export { Label, type LabelProps } from './Label.tsx'
 export { LabelMeta } from './Label.meta.ts'
 export { Link, type LinkProps } from './Link.tsx'
 export { LinkMeta } from './Link.meta.ts'
+export {
+  Dark,
+  Light,
+  LocalTheme,
+  type DarkProps,
+  type LightProps,
+  type LocalThemeProps,
+} from './LocalTheme.tsx'
 export {
   Menu,
   type MenuEmptyProps,

package/src/hooks/useCSSProp.ts

@@ -8,7 +8,7 @@ import {
   type EDSComponent,
 } from '@edgeandnode/eds-css'
 
-import { styleScheduler } from '../utils/index.ts'
+import { styleScheduler } from '../utils/internal/index.ts'
 
 /**
  * Returns a `ref` to set on an element, and an async function to get the current value of a CSS

package/src/hooks/useEDS.ts

@@ -1,19 +1,43 @@
 import { useContext } from 'react'
 
-import { EDSContext } from '../EDSContext.ts'
+import { EDSContext, LocalThemeContext, THEME_CLASSES } from '../EDSContext.ts'
 
 /** Throws an error if used outside of a `EDSProvider`. */
 export function useEDS() {
   const context = useContext(EDSContext)
+  const localTheme = useContext(LocalThemeContext)
 
   if (context === null) {
     throw new Error('EDS components must be wrapped in a `EDSProvider`')
   }
 
   return {
+    /**
+     * The page's theme, as set on `EDSProvider` or with `setTheme`: `'dark'`, `'light'`, or
+     * `'system'` (follows `systemTheme`).
+     */
     theme: context.theme,
-    activeTheme: context.activeTheme,
+    /** Changes the page's theme (use `ThemeSwitcher` for the UI) */
     setTheme: context.setTheme,
+    /** The theme the OS prefers (`prefers-color-scheme`), which the `'system'` theme follows. */
+    systemTheme: context.systemTheme,
+    /**
+     * The theme of the nearest `Dark`, `Light`, or `LocalTheme` ancestor, or `undefined` if there's
+     * none.
+     */
+    localTheme,
+    /**
+     * The theme content is rendered in: `localTheme`, or the page's theme with `'system'` resolved
+     * to `systemTheme`.
+     */
+    activeTheme: localTheme ?? (context.theme === 'system' ? context.systemTheme : context.theme),
+    /**
+     * The class of the nearest `Dark`, `Light`, or `LocalTheme` ancestor, or `undefined` if there's
+     * none. Add it to content rendered outside of that ancestor in the DOM (e.g. with
+     * `createPortal`) so it keeps its theme.
+     */
+    localThemeClass: localTheme !== undefined ? THEME_CLASSES[localTheme] : undefined,
+    /** The `dir` and `lang` of `EDSProvider`, to spread on content rendered outside of it. */
     dirProps: {
       dir: context.direction,
       lang: context.language,

package/src/hooks/useStyleObserver.ts

@@ -1,7 +1,8 @@
 import { useCallback, useLayoutEffect, useRef, type Ref } from 'react'
 import { useMergedRefs } from '@base-ui/utils/useMergedRefs'
 
-import { styleObserver, styleScheduler, type StyleObserverRecord } from '../utils/index.ts'
+import { styleObserver, type StyleObserverRecord } from '../utils/index.ts'
+import { styleScheduler } from '../utils/internal/index.ts'
 import { useEffectWithRefDeps } from './useEffectWithRefDeps.ts'
 
 /**

package/src/icons/CalendarDynamicIcon.tsx

@@ -16,6 +16,7 @@ export interface CalendarDynamicIconProps extends Omit<IconProps, 'alt'> {
 
 export function CalendarDynamicIcon({
   alt,
+  // oxlint-disable-next-line react/purity -- `useState(() => new Date())` would need `'use client'`, which would cause hydration mismatches (time zone, locale) where this is rendered by a server component
   date = new Date(),
   ...props
 }: CalendarDynamicIconProps) {

package/src/index.ts

@@ -1,2 +1,3 @@
 export * from './components/index.ts'
-export { EDSProvider } from './EDSProvider.tsx'
+export { EDSProvider, type ResolvedTheme, type Theme } from './EDSProvider.tsx'
+export { getThemeFromCookies } from './theme-persistence.ts'

package/src/theme-persistence.ts

@@ -0,0 +1,31 @@
+// Not a client module, so server components can call `getThemeFromCookies`
+
+import type { Theme } from './EDSContext.ts'
+
+export const PERSISTENCE_KEY = 'eds-active-theme'
+export const COOKIE_REGEX = new RegExp(`(?:^|;\\s*)${PERSISTENCE_KEY}=([^;]+)`)
+
+export const VALID_THEMES: readonly Theme[] = ['dark', 'light', 'system']
+
+export function isValidTheme(value: unknown): value is Theme {
+  return typeof value === 'string' && (VALID_THEMES as readonly string[]).includes(value)
+}
+
+export function parseThemeCookie(cookies: string | null) {
+  const value = cookies?.match(COOKIE_REGEX)?.[1]
+  return isValidTheme(value) ? value : undefined
+}
+
+/**
+ * Returns the theme saved by `EDSProvider`'s `persistTheme="cookie"` from the request's headers, or
+ * `undefined` if there's none. Pass the result to `defaultTheme`, so the server renders the saved
+ * theme too.
+ *
+ * @example
+ *   ````tsx
+ *   <EDSProvider persistTheme="cookie" defaultTheme={getThemeFromCookies(await headers())}>
+ *   ````
+ */
+export function getThemeFromCookies(headers: Pick<Headers, 'get'>) {
+  return parseThemeCookie(headers.get('cookie'))
+}

package/src/utils/getReactNodeKey.ts

@@ -2,6 +2,7 @@ import { Children, isValidElement, type ReactNode } from 'react'
 
 import { getKey } from '@edgeandnode/eds-utils'
 
+import { resolveLazy } from './internal/index.ts'
 import { reactNodeToString } from './reactNodeToString.ts'
 
 /**
@@ -12,18 +13,33 @@ import { reactNodeToString } from './reactNodeToString.ts'
  * @returns A string key that uniquely identifies the node structure and content.
  */
 export function getReactNodeKey(reactNode: ReactNode): string {
-  const keys =
-    Children.map(reactNode, (child) => {
-      if (!child || typeof child === 'boolean') {
-        return 'empty'
-      }
-      if (!isValidElement(child)) {
-        return getKey(child)
-      }
-      if (child.key !== null) {
-        return `key:${child.key}`
-      }
-      return `${getKey(child.type)}:${reactNodeToString(child)}`
-    }) ?? []
-  return keys.length > 0 ? keys.join('|') : 'empty'
+  try {
+    const keys =
+      Children.map(reactNode, (child) => {
+        if (!child || typeof child === 'boolean') {
+          return 'empty'
+        }
+        if (!isValidElement(child)) {
+          return getKey(child)
+        }
+        if (child.key !== null) {
+          return `key:${child.key}`
+        }
+        /**
+         * Key the type by the component it resolves to, so that identical content created by a
+         * server component gets the same key in every server response (each of which has new lazy
+         * types)
+         */
+        return `${getKey(resolveLazy(child.type))}:${reactNodeToString(child)}`
+      }) ?? []
+    return keys.length > 0 ? keys.join('|') : 'empty'
+  } catch (error) {
+    /**
+     * Resolving a lazy value (e.g. from a server component) suspends (throws a thenable) while it's
+     * still loading, which isn't possible in effects, where this is also called. Fall back to the
+     * node's identity then, but let any other error through.
+     */
+    if (typeof error !== 'object' || error === null || !('then' in error)) throw error
+    return getKey(reactNode)
+  }
 }

package/src/utils/index.ts

@@ -3,12 +3,12 @@ export { getAssetUrl } from './getAssetUrl.ts'
 export { getCSSPropsAttributes } from './getCSSPropsAttributes.ts'
 export { getReactNodeKey } from './getReactNodeKey.ts'
 export { InlineCounter } from './InlineCounter.tsx'
+export { isComponentType } from './isComponentType.ts'
 export { isReactNode } from './isReactNode.ts'
 export { reactNodeToString } from './reactNodeToString.ts'
 export { RenderCount } from './RenderCount.tsx'
 export { setInputValue } from './setInputValue.ts'
 export { splitProps } from './splitProps.ts'
 export { styleObserver, type StyleObserverRecord } from './styleObserver.ts'
-export { styleScheduler } from './styleScheduler.ts'
 export { trimReactNode } from './trimReactNode.tsx'
 export type { OptionValue, Stringifiable } from './types.ts'

package/src/utils/internal/getTooltipProps.ts

@@ -0,0 +1,25 @@
+import type { TooltipProps } from '../../components/Tooltip.tsx'
+
+/**
+ * Normalizes a component's `tooltip` prop, which accepts either the tooltip's content or its props.
+ * Checks for props (a plain object that isn't a React node) rather than for content, so that any
+ * kind of node is treated as content, including ones that `isReactNode` doesn't recognize (e.g.
+ * portals or promises).
+ */
+export function getTooltipProps(
+  tooltip: TooltipProps['content'] | Omit<TooltipProps, 'children'>,
+): Omit<TooltipProps, 'children'> {
+  if (tooltip === undefined) return {}
+  return isTooltipProps(tooltip) ? tooltip : { content: tooltip }
+}
+
+function isTooltipProps(
+  tooltip: Exclude<TooltipProps['content'], undefined> | Omit<TooltipProps, 'children'>,
+): tooltip is Omit<TooltipProps, 'children'> {
+  return (
+    typeof tooltip === 'object' &&
+    tooltip !== null &&
+    !('$$typeof' in tooltip) &&
+    [Object.prototype, null].includes(Object.getPrototypeOf(tooltip))
+  )
+}

package/src/utils/internal/index.ts

@@ -0,0 +1,3 @@
+export { getTooltipProps } from './getTooltipProps.ts'
+export { isLazy, resolveLazy } from './resolveLazy.ts'
+export { styleScheduler } from './styleScheduler.ts'

package/src/utils/internal/resolveLazy.ts

@@ -0,0 +1,44 @@
+import { Lazy } from 'react-is'
+
+/**
+ * Whether `value` is a lazy value, which is how the React Server Components payload can encode an
+ * element passed as a prop from a server component (e.g. when it's rendered by an async server
+ * component), or the `type` of an element created by a server component (so the client can suspend
+ * on that component's code). `React.lazy()` components are lazy values too.
+ *
+ * Not to be confused with `react-is`'s `isLazy`, which checks whether an element's type is lazy.
+ */
+export function isLazy(
+  value: unknown,
+): value is { _payload: unknown; _init: (payload: unknown) => unknown } {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    '$$typeof' in value &&
+    value.$$typeof === Lazy &&
+    '_payload' in value &&
+    '_init' in value &&
+    typeof value._init === 'function'
+  )
+}
+
+/**
+ * Resolves a lazy value (see `isLazy`) to what it stands for. React resolves lazy values when
+ * rendering them, but code that inspects nodes or element types (`isValidElement`, `cloneElement`,
+ * reading `props`, comparing `type`, etc.) must resolve them first. Suspends (throws) while the
+ * value's content or code is still loading, so it must be called during render.
+ *
+ * React has no public API for this. Its `Children` utilities resolve lazy values but only keep
+ * renderable results, so they drop a function component and throw on a `memo` or `forwardRef` one.
+ * This relies on the same internal `_init` and `_payload` fields they use, which is why it's kept
+ * internal rather than offered as public API. Returns other values as is, including lazy ones in an
+ * unexpected shape.
+ *
+ * The return type is the same as the argument's because TypeScript already types a lazy value as
+ * what it resolves to.
+ */
+export function resolveLazy<Value>(value: Value): Value {
+  let resolvedValue: unknown = value
+  while (isLazy(resolvedValue)) resolvedValue = resolvedValue._init(resolvedValue._payload)
+  return resolvedValue as Value
+}

package/src/utils/isComponentType.ts

@@ -0,0 +1,27 @@
+import type { ComponentType, ReactNode } from 'react'
+import { ForwardRef, Memo } from 'react-is'
+
+import { isLazy, resolveLazy } from './internal/index.ts'
+
+/**
+ * Whether `value` is a component (function, class, `forwardRef`, or `memo`) rather than a node.
+ *
+ * Like React's `Children` utilities, this resolves lazy values (e.g. elements from server
+ * components), which suspends while one is still loading, so call it during render.
+ */
+export function isComponentType<Props>(
+  value: ReactNode | ComponentType<Props>,
+): value is ComponentType<Props> {
+  /**
+   * Unlike `react-is`'s `isValidElementType`, which returns `true` for any lazy value, resolving
+   * tells lazy components (e.g. `React.lazy()`) apart from lazy nodes.
+   */
+  if (isLazy(value)) return isComponentType(resolveLazy(value))
+  return (
+    typeof value === 'function' ||
+    (typeof value === 'object' &&
+      value !== null &&
+      '$$typeof' in value &&
+      (value.$$typeof === ForwardRef || value.$$typeof === Memo))
+  )
+}

package/src/utils/isReactNode.ts

@@ -1,6 +1,17 @@
 import { isValidElement, type ReactNode } from 'react'
 
+import { isLazy, resolveLazy } from './internal/index.ts'
+
+/**
+ * Whether `value` is a React node: `null`, `undefined`, a string, number, or boolean, an element, a
+ * lazy node (e.g. an element from a server component), or an array of these.
+ *
+ * Like React's `Children` utilities, this resolves lazy values (e.g. elements from server
+ * components), which suspends while one is still loading, so call it during render.
+ */
 export function isReactNode(value: unknown): value is ReactNode {
+  // Resolving tells lazy nodes apart from lazy components (e.g. `React.lazy()`)
+  if (isLazy(value)) return isReactNode(resolveLazy(value))
   return (
     value === null ||
     value === undefined ||

package/src/utils/reactNodeToString.ts

@@ -1,15 +1,22 @@
 import { isValidElement, type ReactElement, type ReactNode } from 'react'
 
+import { isLazy, resolveLazy } from './internal/index.ts'
+
 /**
  * Converts a `ReactNode` to a `string` representation. Extracts text content from React elements
  * recursively.
  *
  * Based on `https://github.com/sunknudsen/react-node-to-string`
  *
+ * Like React's `Children` utilities, this resolves lazy values (e.g. elements from server
+ * components), which suspends while one is still loading, so call it during render.
+ *
  * @param reactNode - The React node to convert to string.
  * @returns The string representation of the node, or empty string for null/undefined/boolean.
  */
 export function reactNodeToString(reactNode: ReactNode): string {
+  if (isLazy(reactNode)) return reactNodeToString(resolveLazy(reactNode))
+
   if (typeof reactNode === 'string') {
     return reactNode
   }

package/src/utils/styleObserver.ts

@@ -1,6 +1,6 @@
 import StyleObserver from 'style-observer'
 
-import { styleScheduler } from './styleScheduler.ts'
+import { styleScheduler } from './internal/index.ts'
 
 export interface StyleObserverRecord<T extends string = string> {
   target: Element

package/src/utils/trimReactNode.tsx

@@ -1,5 +1,7 @@
 import { Children, isValidElement, type ReactElement, type ReactNode } from 'react'
 
+import { isLazy, resolveLazy } from './internal/index.ts'
+
 type Side = 'start' | 'end' | 'both'
 
 /**
@@ -15,6 +17,9 @@ type Side = 'start' | 'end' | 'both'
  * When recursing into a non-string edge child (e.g. a nested fragment), only the corresponding side
  * is trimmed, so that whitespace which is internal to the outer node is preserved.
  *
+ * Like React's `Children` utilities, this resolves lazy values (e.g. elements from server
+ * components), which suspends while one is still loading, so call it during render.
+ *
  * @example
  *   ````tsx
  *   trimReactNode('  hello  ') // 'hello'
@@ -30,6 +35,8 @@ type Side = 'start' | 'end' | 'both'
  * @returns A new `ReactNode` with the requested edge whitespace removed.
  */
 export function trimReactNode(reactNode: ReactNode, side: Side = 'both'): ReactNode {
+  if (isLazy(reactNode)) return trimReactNode(resolveLazy(reactNode), side)
+
   // Handle primitives
   if (typeof reactNode === 'string') {
     switch (side) {

package/dist/utils/styleScheduler.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"styleScheduler.d.ts","sourceRoot":"","sources":["../../src/utils/styleScheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,cAAM,cAAc;IAClB,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,OAAO,CAAqB;IAEpC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAiBzC;IAED;;;OAGG;IACH,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAM/D;CACF;AAGD,eAAO,MAAM,cAAc,gBAAuB,CAAA"}

package/dist/utils/styleScheduler.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"styleScheduler.js","sourceRoot":"","sources":["../../src/utils/styleScheduler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,cAAc;IACV,KAAK,GAAkB,IAAI,CAAA;IAC3B,OAAO,GAAmB,EAAE,CAAA;IAEpC;;;;OAIG;IACH,QAAQ,CAAC,QAAoB;QAC3B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QAE3B,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;YACxB,IAAI,CAAC,KAAK,GAAG,qBAAqB,CAAC,GAAG,EAAE;gBACtC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAA;gBAC9B,IAAI,CAAC,OAAO,GAAG,EAAE,CAAA;gBACjB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAA;gBAEjB,SAAS,CAAC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAA;YACjC,CAAC,CAAC,CAAA;QACJ,CAAC;QAED,OAAO,GAAG,EAAE;YACV,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;YAC5C,IAAI,KAAK,KAAK,CAAC,CAAC;gBAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;QACjD,CAAC,CAAA;IACH,CAAC;IAED;;;OAGG;IACH,gBAAgB,CAAC,OAAgB;QAC/B,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC7B,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE;gBACjB,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAA;YAC3C,CAAC,CAAC,CAAA;QACJ,CAAC,CAAC,CAAA;IACJ,CAAC;CACF;AAED,kDAAkD;AAClD,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,cAAc,EAAE,CAAA"}