ID & Reference Management

/**
 * Generates a unique ID for DOM elements, with SSR safety
 * @param defaultId - Optional default ID to use
 * @returns A unique string ID that's stable across renders
 */
function useId(defaultId?: string): string;

import { useId } from "@react-aria/utils";

function MyComponent() {
  const labelId = useId();
  const inputId = useId("my-input"); // Uses provided ID if no conflicts
  
  return (
    <div>
      <label id={labelId} htmlFor={inputId}>Name</label>
      <input id={inputId} aria-labelledby={labelId} />
    </div>
  );
}

/**
 * Merges two IDs, prioritizing the second ID if different
 * @param idA - First ID
 * @param idB - Second ID 
 * @returns The merged ID (idB takes precedence if different from idA)
 */
function mergeIds(idA: string, idB: string): string;

import { mergeIds, useId } from "@react-aria/utils";

function FormField({ id, ...props }) {
  const defaultId = useId();
  const finalId = mergeIds(defaultId, id);
  
  return <input id={finalId} {...props} />;
}

/**
 * Generates an ID and checks if it exists in DOM after render
 * @param depArray - Optional dependency array for recalculating DOM presence
 * @returns ID string that's stable across renders
 */
function useSlotId(depArray?: ReadonlyArray<any>): string;

import { useSlotId } from "@react-aria/utils";

function Dialog({ children }) {
  const titleId = useSlotId([children]);
  
  return (
    <div 
      role="dialog" 
      aria-labelledby={titleId} // Only set if title element exists
    >
      {children}
    </div>
  );
}

function DialogTitle({ children, ...props }) {
  const id = useSlotId();
  return <h2 id={id} {...props}>{children}</h2>;
}

/**
 * Combines multiple refs into a single ref function
 * @param refs - Array of refs (object refs, callback refs, or null/undefined)
 * @returns Combined ref function that updates all provided refs
 */
function mergeRefs<T>(...refs: (Ref<T> | null | undefined)[]): Ref<T>;

import { mergeRefs } from "@react-aria/utils";
import { useRef, forwardRef } from "react";

const MyInput = forwardRef<HTMLInputElement, InputProps>((props, ref) => {
  const localRef = useRef<HTMLInputElement>(null);
  const combinedRef = mergeRefs(ref, localRef);
  
  return <input ref={combinedRef} {...props} />;
});

/**
 * Converts callback refs or forwarded refs to object refs
 * @param ref - Original ref (callback, object, or null)
 * @returns Object ref that updates the original ref
 */
function useObjectRef<T>(ref?: ForwardedRef<T>): MutableRefObject<T | null>;

import { useObjectRef } from "@react-aria/utils";
import { useButton } from "@react-aria/button";
import { forwardRef } from "react";

const Button = forwardRef<HTMLButtonElement, ButtonProps>((props, ref) => {
  const objectRef = useObjectRef(ref);
  const { buttonProps } = useButton(props, objectRef);
  
  return <button ref={objectRef} {...buttonProps} />;
});

/**
 * Synchronizes a ref with a context value
 * @param context - Context to sync with
 * @param ref - Ref to synchronize
 */
function useSyncRef<T>(context: Context<T>, ref: MutableRefObject<T>): void;

import { useSyncRef } from "@react-aria/utils";
import { createContext, useContext, useRef } from "react";

const MyContext = createContext<HTMLElement | null>(null);

function ContextProvider({ children }) {
  const ref = useRef<HTMLElement>(null);
  useSyncRef(MyContext, ref);
  
  return (
    <MyContext.Provider value={ref.current}>
      <div ref={ref}>
        {children}
      </div>
    </MyContext.Provider>
  );
}

type Ref<T> = MutableRefObject<T> | ((instance: T | null) => void) | null;
type ForwardedRef<T> = ((instance: T | null) => void) | MutableRefObject<T | null> | null;