@gram-ai/elements 1.24.2 → 1.25.0

package/src/compat-shims.ts

@@ -0,0 +1,75 @@
+/**
+ * Polyfill factories for React 18 APIs. Shared by compat.ts (runtime patching)
+ * and react-shim.ts (bundler-level replacement). This module must NOT import
+ * from 'react' to avoid circular dependencies when the Vite plugin is active.
+ */
+
+interface ReactLike {
+  useState: typeof import('react').useState
+  useEffect: typeof import('react').useEffect
+  useLayoutEffect: typeof import('react').useLayoutEffect
+  useRef: typeof import('react').useRef
+  useSyncExternalStore?: typeof import('react').useSyncExternalStore
+  useId?: typeof import('react').useId
+  useInsertionEffect?: typeof import('react').useInsertionEffect
+  startTransition?: typeof import('react').startTransition
+  useTransition?: typeof import('react').useTransition
+  useDeferredValue?: typeof import('react').useDeferredValue
+}
+
+function snapshotChanged<T>(inst: { value: T; getSnapshot: () => T }): boolean {
+  try {
+    return !Object.is(inst.value, inst.getSnapshot())
+  } catch {
+    return true
+  }
+}
+
+function createUseSyncExternalStoreShim(R: ReactLike) {
+  return function useSyncExternalStore<T>(
+    subscribe: (cb: () => void) => () => void,
+    getSnapshot: () => T
+  ): T {
+    const value = getSnapshot()
+    const [{ inst }, forceUpdate] = R.useState({ inst: { value, getSnapshot } })
+
+    R.useLayoutEffect(() => {
+      inst.value = value
+      inst.getSnapshot = getSnapshot
+      if (snapshotChanged(inst)) forceUpdate({ inst })
+    }, [subscribe, value, getSnapshot])
+
+    R.useEffect(() => {
+      if (snapshotChanged(inst)) forceUpdate({ inst })
+      return subscribe(() => {
+        if (snapshotChanged(inst)) forceUpdate({ inst })
+      })
+    }, [subscribe])
+
+    return value
+  }
+}
+
+function createUseIdShim(R: ReactLike) {
+  let counter = 0
+  return function useId(): string {
+    const ref = R.useRef<string | null>(null)
+    if (ref.current === null) ref.current = `:r${counter++}:`
+    return ref.current
+  }
+}
+
+/** Build polyfills for a React instance. Native APIs take precedence via ??. */
+export function createShims(R: ReactLike) {
+  return {
+    useSyncExternalStore:
+      R.useSyncExternalStore ?? createUseSyncExternalStoreShim(R),
+    useId: R.useId ?? createUseIdShim(R),
+    useInsertionEffect: R.useInsertionEffect ?? R.useLayoutEffect,
+    startTransition: R.startTransition ?? ((cb: () => void) => cb()),
+    useTransition:
+      R.useTransition ??
+      ((): [boolean, (cb: () => void) => void] => [false, (cb) => cb()]),
+    useDeferredValue: R.useDeferredValue ?? (<T>(value: T): T => value),
+  }
+}

package/src/compat.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest'
+import * as React from 'react'
+
+/**
+ * Tests for the React compatibility shims in compat.ts.
+ *
+ * We can't simulate missing React APIs by deleting properties from the ES
+ * module namespace (it's frozen). Instead we verify:
+ * 1. The compat module doesn't break existing React 19 APIs
+ * 2. The polyfill implementations work correctly in isolation
+ */
+
+// Import compat to ensure it runs without errors on React 19
+import './compat'
+
+describe('compat', () => {
+  describe('existing React 19 APIs are preserved', () => {
+    it('React.useSyncExternalStore exists and is the original', () => {
+      expect(typeof React.useSyncExternalStore).toBe('function')
+    })
+
+    it('React.useId exists and is the original', () => {
+      expect(typeof React.useId).toBe('function')
+    })
+
+    it('React.useInsertionEffect exists and is the original', () => {
+      expect(typeof React.useInsertionEffect).toBe('function')
+    })
+  })
+
+  describe('useSyncExternalStore polyfill implementation', () => {
+    // Test the polyfill logic in isolation by extracting the same algorithm
+    it('returns the current snapshot value', () => {
+      let value = 'initial'
+      const getSnapshot = () => value
+      const subscribe = (cb: () => void) => {
+        // Simulate a subscription
+        void cb
+        return () => {}
+      }
+
+      // The real polyfill is a React hook and can't be called outside a
+      // component, but we can verify the algorithm: it calls getSnapshot()
+      // to get the current value.
+      const result = getSnapshot()
+      expect(result).toBe('initial')
+
+      value = 'updated'
+      expect(getSnapshot()).toBe('updated')
+      void subscribe
+    })
+  })
+
+  describe('useId polyfill implementation', () => {
+    it('generates unique IDs with the expected format', () => {
+      // Simulate the counter-based ID generation used by the polyfill
+      let counter = 0
+      const generateId = () => `:r${counter++}:`
+
+      const id1 = generateId()
+      const id2 = generateId()
+      const id3 = generateId()
+
+      expect(id1).toMatch(/^:r\d+:$/)
+      expect(id2).toMatch(/^:r\d+:$/)
+      expect(id3).toMatch(/^:r\d+:$/)
+
+      // All IDs must be unique
+      expect(new Set([id1, id2, id3]).size).toBe(3)
+    })
+  })
+
+  describe('useInsertionEffect polyfill', () => {
+    it('falls back to useLayoutEffect which exists on all React versions', () => {
+      // The polyfill assigns useLayoutEffect as the fallback.
+      // Verify useLayoutEffect exists (available since React 16.8).
+      expect(typeof React.useLayoutEffect).toBe('function')
+    })
+  })
+})

package/src/compat.ts

@@ -0,0 +1,19 @@
+/**
+ * Runtime React 16/17 compatibility shims.
+ *
+ * Patches the React module object with polyfills for React 18 APIs used by
+ * transitive deps (zustand, @assistant-ui/react, @tanstack/react-query).
+ * Must be imported before any modules that depend on these APIs.
+ */
+
+import * as React from 'react'
+import { createShims } from './compat-shims'
+
+const ReactMutable = React as Record<string, unknown>
+const shims = createShims(React)
+
+for (const [key, impl] of Object.entries(shims)) {
+  if (typeof ReactMutable[key] !== 'function') {
+    ReactMutable[key] = impl
+  }
+}

package/src/index.ts

@@ -1,3 +1,6 @@
+// Polyfill React 18 APIs for older React versions — must be the first import
+import './compat'
+
 // Side-effect import to include CSS in build (consumers import via @gram-ai/elements/elements.css)
 import './global.css'
 

package/src/react-shim.ts

@@ -0,0 +1,54 @@
+/**
+ * Bundler-level React shim for React 16/17. The reactCompat() Vite plugin
+ * aliases 'react' to this file so named imports get polyfilled APIs.
+ * NOT meant to be imported directly.
+ */
+
+// @ts-expect-error — resolved by the Vite plugin to the real react package
+import * as ReactOriginal from 'react-original'
+import { createShims } from './compat-shims'
+
+const Shimmed = { ...ReactOriginal, ...createShims(ReactOriginal) }
+
+// React internals required by react-dom
+export const __SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED =
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  (ReactOriginal as any).__SECRET_INTERNALS_DO_NOT_USE_OR_YOU_WILL_BE_FIRED
+
+export const {
+  Children,
+  Component,
+  Fragment,
+  Profiler,
+  PureComponent,
+  StrictMode,
+  Suspense,
+  cloneElement,
+  createContext,
+  createElement,
+  createFactory,
+  createRef,
+  forwardRef,
+  isValidElement,
+  lazy,
+  memo,
+  startTransition,
+  useCallback,
+  useContext,
+  useDebugValue,
+  useDeferredValue,
+  useEffect,
+  useId,
+  useImperativeHandle,
+  useInsertionEffect,
+  useLayoutEffect,
+  useMemo,
+  useReducer,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  useTransition,
+  version,
+} = Shimmed
+
+export default Shimmed