docs(modal): recommend ref over css selector

Author: stephl3

packages/modal/README.md

@@ -140,7 +140,7 @@ When a Modal opens, it automatically manages focus to ensure proper accessibilit
 
 1. **`initialFocus` prop**: The specified element receives focus
    - String selector: `initialFocus="#submit-button"`
-   - React ref: `initialFocus={submitButtonRef}`
+   - React ref: `initialFocus={submitButtonRef}` (recommended over string selector for better type safety)
 2. **`autoFocus` attribute**: If any child element has the `autoFocus` attribute, that element receives focus
 3. **First focusable element**: If `initialFocus` is `"auto"` and no child element has the `autoFocus` attribute, the first focusable element receives focus
 4. **No focus**: If `initialFocus` is `null`, no automatic focus occurs

packages/modal/src/Modal/Modal.types.ts

@@ -52,7 +52,7 @@ export interface ModalProps
    * **Options:**
    * - `"auto"`: Automatically focuses the first focusable element in the modal
    * - `string`: CSS selector passed to `querySelector()` to specify an element
-   * - `React.RefObject<HTMLElement>`: Reference to the element that should receive focus
+   * - `React.RefObject<HTMLElement>`: Reference to the element that should receive focus. This is recommended over using a CSS selector for better type safety.
    * - `null`: Disables automatic focus management. Use sparingly - disabling focus management may create accessibility issues
    *
    * **Priority order:**
@@ -70,7 +70,7 @@ export interface ModalProps
    * </Modal>
    *
    * @example
-   * // Using a ref
+   * // Using a ref (recommended over selector)
    * const submitRef = useRef<HTMLButtonElement>(null);
    * <Modal initialFocus={submitRef}>
    *   <button ref={submitRef}>Submit</button>