refactor: replace ID generation with useStableId hook and update CallbackProps type

- Updated SuperDocEditor to use the new useStableId hook for generating stable IDs.
- Removed the old generateId function and adjusted ID generation logic accordingly.
- Changed the type definition for callbacks from CallbacksType to the newly defined CallbackProps interface in types.ts.

Author: tupizz

packages/react/src/SuperDocEditor.tsx

@@ -1,6 +1,7 @@
 import { forwardRef, useEffect, useImperativeHandle, useRef, useState, type ForwardedRef } from 'react';
-import { generateId } from './utils';
+import { useStableId } from './utils';
 import type {
+  CallbackProps,
   DocumentMode,
   SuperDocEditorProps,
   SuperDocInstance,
@@ -12,16 +13,6 @@ import type {
   SuperDocExceptionEvent,
 } from './types';
 
-/** Callback props type for the ref */
-type CallbacksType = {
-  onReady?: (event: SuperDocReadyEvent) => void;
-  onEditorCreate?: (event: SuperDocEditorCreateEvent) => void;
-  onEditorDestroy?: () => void;
-  onEditorUpdate?: (event: SuperDocEditorUpdateEvent) => void;
-  onContentError?: (event: SuperDocContentErrorEvent) => void;
-  onException?: (event: SuperDocExceptionEvent) => void;
-};
-
 /**
  * SuperDocEditor - React wrapper component for SuperDoc
  *
@@ -72,17 +63,18 @@ function SuperDocEditorInner(props: SuperDocEditorProps, ref: ForwardedRef<Super
   const toolbarContainerRef = useRef<HTMLDivElement | null>(null);
 
   // Generate stable IDs once per component instance (use provided id if available)
+  const generatedId = useStableId();
   const idsRef = useRef<{ containerId: string; toolbarId: string } | null>(null);
   if (idsRef.current === null) {
-    const baseId = id ?? generateId();
+    const baseId = id ?? `superdoc${generatedId}`;
     idsRef.current = { containerId: baseId, toolbarId: `${baseId}-toolbar` };
   }
   const { containerId, toolbarId } = idsRef.current;
 
   const [isLoading, setIsLoading] = useState(true);
 
   // Store callbacks in refs to avoid triggering effect on callback changes
-  const callbacksRef = useRef<CallbacksType>({
+  const callbacksRef = useRef<CallbackProps>({
     onReady,
     onEditorCreate,
     onEditorDestroy,

packages/react/src/types.ts

@@ -100,7 +100,7 @@ type ExplicitCallbackProps =
  * Explicitly typed callback props to ensure proper TypeScript inference.
  * These override any loosely-typed callbacks from SuperDocConfig.
  */
-interface CallbackProps {
+export interface CallbackProps {
   /** Callback when SuperDoc is ready */
   onReady?: (event: SuperDocReadyEvent) => void;
 

packages/react/src/utils.ts

@@ -1,16 +1,27 @@
 /** @module utils */
 
+import * as React from 'react';
+
 /**
- * Generate a unique ID for SuperDoc container elements.
- *
- * Uses a combination of timestamp and random string to ensure uniqueness
- * across multiple instances without relying on a global counter.
- *
- * Note: This function only runs on the client after hydration since
- * IDs are generated in a ref initializer (not during SSR render).
- *
- * @returns A unique identifier string
+ * Polyfill for React.useId() for React versions < 18.
+ * Uses useRef to generate a stable random ID once per component instance.
  */
-export function generateId(): string {
-  return `superdoc-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+function useIdPolyfill(): string {
+  const ref = React.useRef<string | null>(null);
+  if (ref.current === null) {
+    ref.current = `-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+  }
+  return ref.current;
 }
+
+/**
+ * Hook that returns a stable unique ID for the component instance.
+ * Uses React.useId() when available (React 18+), falls back to
+ * useRef-based polyfill for React 16.8+/17.
+ *
+ * The returned value is used as: `superdoc${useStableId()}`
+ * - React 18+: useId() returns ":r0:" → "superdoc:r0:"
+ * - Polyfill: returns "-1707345123456-abc1d2e" → "superdoc-1707345123456-abc1d2e"
+ */
+export const useStableId: () => string =
+  typeof (React as any).useId === 'function' ? (React as any).useId : useIdPolyfill;