ui-soxo-bootstrap-core 2.6.40-dev.1 → 2.6.40-dev.12

package/core/components/external-window/DEVELOPER_GUIDE.md

@@ -1,705 +1,705 @@
-# ExternalWindow Component
-
-A React component that renders content in a separate browser window with full style inheritance and keyboard shortcuts support.
-
-## Features
-
-- 🪟 Opens content in a new browser window
-- 🎨 Automatically copies parent window styles (Ant Design, SCSS, etc.)
-- ⚨️ Customizable keyboard shortcuts
-- 📍 Flexible positioning (manual or auto-center)
-- 🔄 React Portal-based rendering
-- ⚡ No white flash - instant background color matching
-- 🧹 Automatic cleanup on unmount
-
-## Quick Start
-
-```jsx
-import { useState, useCallback } from 'react';
-import { ExternalWindow } from './ExternalWindow';
-import { Button } from 'antd';
-
-function App() {
-  const [showWindow, setShowWindow] = useState(false);
-
-  // Use useCallback to prevent re-renders
-  const handleClose = useCallback(() => {
-    setShowWindow(false);
-  }, []);
-
-  return (
-    <>
-      <Button onClick={() => setShowWindow(true)}>Open New Window</Button>
-
-      {showWindow && (
-        <ExternalWindow title="My External Window" onClose={handleClose}>
-          <div style={{ padding: 20 }}>
-            <h1>Hello from external window!</h1>
-            <p>All your styles are automatically copied here.</p>
-          </div>
-        </ExternalWindow>
-      )}
-    </>
-  );
-}
-```
-
-## Props Reference
-
-### Props
-
-| Prop           | Type            | Default                                      | Description                                                       |
-| -------------- | --------------- | -------------------------------------------- | ----------------------------------------------------------------- |
-| `children`     | `ReactNode`     | **required**                                 | Content to render in the new window                               |
-| `onClose`      | `Function`      | **required**                                 | Callback when window closes (wrap in `useCallback`)               |
-| `title`        | `string`        | `'New Window'`                               | Window title (shown in browser tab)                               |
-| `width`        | `number`        | `600`                                        | Window width in pixels                                            |
-| `height`       | `number`        | `400`                                        | Window height in pixels                                           |
-| `left`         | `number`        | `200`                                        | Window X position (overridden by `centerScreen`)                  |
-| `top`          | `number`        | `200`                                        | Window Y position (overridden by `centerScreen`)                  |
-| `copyStyles`   | `boolean`       | `true`                                       | Whether to copy parent window styles                              |
-| `centerScreen` | `string\|false` | `false`                                      | Center window: `'horizontal'`, `'vertical'`, `'both'`, or `false` |
-| `shortcuts`    | `Object`        | `{ close: 'Escape', focus: 'Ctrl+Shift+F' }` | Keyboard shortcuts configuration                                  |
-| `onMinimize`   | `Function`      | `undefined`                                  | Callback when window is minimized                                 |
-| `onMaximize`   | `Function`      | `undefined`                                  | Callback when window is maximized                                 |
-
-## Usage Examples
-
-### Centered Window
-
-```jsx
-import { useState, useCallback } from 'react';
-
-function App() {
-  const [showWindow, setShowWindow] = useState(false);
-
-  const handleClose = useCallback(() => {
-    setShowWindow(false);
-  }, []);
-
-  return (
-    <>
-      <Button onClick={() => setShowWindow(true)}>Open Centered</Button>
-
-      {showWindow && (
-        <ExternalWindow title="Centered Window" width={800} height={600} centerScreen="both" onClose={handleClose}>
-          <YourContent />
-        </ExternalWindow>
-      )}
-    </>
-  );
-}
-```
-
-### Custom Positioning
-
-```jsx
-const handleClose = useCallback(() => setShowWindow(false), []);
-
-<ExternalWindow title="Custom Position" width={1000} height={700} left={100} top={50} onClose={handleClose}>
-  <YourContent />
-</ExternalWindow>;
-```
-
-### With Custom Keyboard Shortcuts
-
-```jsx
-const handleClose = useCallback(() => setShowWindow(false), []);
-const handleMinimize = useCallback(() => console.log('Minimized'), []);
-const handleMaximize = useCallback(() => console.log('Maximized'), []);
-
-<ExternalWindow
-  title="With Shortcuts"
-  shortcuts={{
-    close: 'Escape', // Close window
-    focus: 'Ctrl+Shift+F', // Focus window
-    minimize: 'Ctrl+M', // Minimize window
-    maximize: 'Ctrl+Shift+M', // Maximize window
-  }}
-  onClose={handleClose}
-  onMinimize={handleMinimize}
-  onMaximize={handleMaximize}
->
-  <YourContent />
-</ExternalWindow>;
-```
-
-### Without Style Copying
-
-```jsx
-const handleClose = useCallback(() => setShowWindow(false), []);
-
-<ExternalWindow title="No Styles" copyStyles={false} onClose={handleClose}>
-  {/* You'll need to add inline styles or external CSS links */}
-  <div style={{ padding: 20, fontFamily: 'Arial' }}>
-    <h1>Plain content</h1>
-  </div>
-</ExternalWindow>;
-```
-
-### Managing Multiple Windows
-
-```jsx
-function MultiWindowApp() {
-  const [windows, setWindows] = useState([]);
-
-  const openWindow = useCallback((config) => {
-    const id = Date.now();
-    setWindows((prev) => [...prev, { id, ...config }]);
-  }, []);
-
-  const closeWindow = useCallback((id) => {
-    setWindows((prev) => prev.filter((w) => w.id !== id));
-  }, []);
-
-  return (
-    <>
-      <Button
-        onClick={() =>
-          openWindow({
-            title: 'Window ' + (windows.length + 1),
-            content: <MyComponent />,
-          })
-        }
-      >
-        Add Window
-      </Button>
-
-      {windows.map(({ id, title, content }) => (
-        <ExternalWindow key={id} title={title} onClose={() => closeWindow(id)}>
-          {content}
-        </ExternalWindow>
-      ))}
-    </>
-  );
-}
-```
-
-### Full-Featured Dashboard Example
-
-```jsx
-import { useState, useCallback } from 'react';
-import { ExternalWindow } from './ExternalWindow';
-import { Button, Card, Space } from 'antd';
-
-function Dashboard() {
-  const [windows, setWindows] = useState({
-    chart: false,
-    report: false,
-    settings: false,
-  });
-
-  const openWindow = useCallback((name) => {
-    setWindows((prev) => ({ ...prev, [name]: true }));
-  }, []);
-
-  const closeWindow = useCallback((name) => {
-    setWindows((prev) => ({ ...prev, [name]: false }));
-  }, []);
-
-  return (
-    <div style={{ padding: 24 }}>
-      <Space>
-        <Button onClick={() => openWindow('chart')}>Open Chart</Button>
-        <Button onClick={() => openWindow('report')}>Open Report</Button>
-        <Button onClick={() => openWindow('settings')}>Open Settings</Button>
-      </Space>
-
-      {windows.chart && (
-        <ExternalWindow title="Analytics Chart" width={1200} height={800} centerScreen="both" onClose={() => closeWindow('chart')}>
-          <Card title="Sales Analytics" style={{ margin: 20 }}>
-            {/* Your chart component */}
-          </Card>
-        </ExternalWindow>
-      )}
-
-      {windows.report && (
-        <ExternalWindow title="Monthly Report" width={900} height={700} left={50} top={50} onClose={() => closeWindow('report')}>
-          <div style={{ padding: 20 }}>{/* Your report component */}</div>
-        </ExternalWindow>
-      )}
-
-      {windows.settings && (
-        <ExternalWindow
-          title="Settings"
-          width={600}
-          height={500}
-          centerScreen="horizontal"
-          shortcuts={{
-            close: 'Escape',
-            focus: 'Ctrl+S',
-          }}
-          onClose={() => closeWindow('settings')}
-        >
-          <div style={{ padding: 20 }}>{/* Your settings component */}</div>
-        </ExternalWindow>
-      )}
-    </div>
-  );
-}
-```
-
-### With Shared State
-
-```jsx
-function StatefulWindow() {
-  const [showWindow, setShowWindow] = useState(false);
-  const [data, setData] = useState([]);
-
-  const handleClose = useCallback(() => {
-    setShowWindow(false);
-  }, []);
-
-  return (
-    <>
-      <Button onClick={() => setShowWindow(true)}>Open Data Viewer</Button>
-
-      {showWindow && (
-        <ExternalWindow title="Data Viewer" onClose={handleClose}>
-          {/* State is shared between parent and child window */}
-          <DataTable data={data} onUpdate={setData} />
-        </ExternalWindow>
-      )}
-    </>
-  );
-}
-```
-
-## Keyboard Shortcuts
-
-### Default Shortcuts
-
-- **Escape**: Close window
-- **Ctrl+Shift+F**: Focus window
-
-### Customizing Shortcuts
-
-Define custom shortcuts using the `shortcuts` prop. Shortcuts support modifiers:
-
-- `Ctrl` / `Control`
-- `Shift`
-- `Alt`
-- `Meta` (Command on Mac)
-
-**Format Examples:**
-
-```javascript
-shortcuts={{
-  close: 'Escape',
-  focus: 'Ctrl+Shift+F',
-  minimize: 'Ctrl+M',
-  maximize: 'Ctrl+Shift+M',
-  save: 'Ctrl+S',
-  custom: 'Alt+K'
-}}
-```
-
-## How It Works
-
-### Style Inheritance
-
-When `copyStyles={true}` (default):
-
-1. **Instant Background**: Critical inline styles are applied immediately, inheriting the parent window's background color and text color
-2. **No White Flash**: The window opens with proper styling from the start
-3. **Async Loading**: Full stylesheets are copied asynchronously for smooth rendering
-4. **Complete Coverage**: All parent window styles are copied:
-   - Ant Design themes
-   - SCSS/CSS modules
-   - Custom fonts
-   - External stylesheets
-   - Inline styles
-
-### Window Lifecycle
-
-1. Window opens with specified dimensions and position
-2. Critical styles applied instantly (background, colors, layout)
-3. Full styles copied from parent window
-4. Content rendered via React Portal
-5. Event listeners attached (keyboard shortcuts, window close)
-6. Automatic cleanup on component unmount
-
-### Performance Optimizations
-
-- **Single Window Creation**: Window is created once and reused throughout component lifecycle
-- **Async Style Loading**: Styles are copied using `requestAnimationFrame` to avoid blocking
-- **Stable References**: Uses `useCallback` and `useMemo` to prevent unnecessary re-renders
-- **Efficient Cleanup**: Proper event listener removal and window closure
-
-## Best Practices
-
-### ✅ Do's
-
-```jsx
-// Use useCallback for all callbacks
-const handleClose = useCallback(() => setShowWindow(false), []);
-const handleMinimize = useCallback(() => console.log('Min'), []);
-
-// Center important windows
-<ExternalWindow centerScreen="both" ... />
-
-// Provide meaningful titles
-<ExternalWindow title="Sales Report - Q4 2024" ... />
-
-// Use appropriate dimensions
-<ExternalWindow width={1200} height={800} ... />
-```
-
-### ❌ Don'ts
-
-```jsx
-// Don't use inline functions - causes re-renders
-<ExternalWindow onClose={() => setShowWindow(false)} ... />
-
-// Don't forget to handle window state
-{showWindow && <ExternalWindow ... />}
-
-// Don't use tiny dimensions
-<ExternalWindow width={100} height={100} ... />
-
-// Don't disable style copying without reason
-<ExternalWindow copyStyles={false} ... />
-```
-
-## Advanced Patterns
-
-### Window with Tabs
-
-```jsx
-function TabbedWindow() {
-  const [showWindow, setShowWindow] = useState(false);
-  const [activeTab, setActiveTab] = useState('1');
-
-  const handleClose = useCallback(() => setShowWindow(false), []);
-
-  return (
-    <>
-      <Button onClick={() => setShowWindow(true)}>Open</Button>
-
-      {showWindow && (
-        <ExternalWindow title="Multi-Tab Window" width={1000} height={700} centerScreen="both" onClose={handleClose}>
-          <Tabs activeKey={activeTab} onChange={setActiveTab}>
-            <TabPane tab="Dashboard" key="1">
-              <Dashboard />
-            </TabPane>
-            <TabPane tab="Settings" key="2">
-              <Settings />
-            </TabPane>
-            <TabPane tab="Reports" key="3">
-              <Reports />
-            </TabPane>
-          </Tabs>
-        </ExternalWindow>
-      )}
-    </>
-  );
-}
-```
-
-### Window with Form Submission
-
-```jsx
-function FormWindow() {
-  const [showWindow, setShowWindow] = useState(false);
-
-  const handleClose = useCallback(() => setShowWindow(false), []);
-
-  const handleSubmit = useCallback((values) => {
-    console.log('Form submitted:', values);
-    setShowWindow(false);
-  }, []);
-
-  return (
-    <>
-      <Button onClick={() => setShowWindow(true)}>Open Form</Button>
-
-      {showWindow && (
-        <ExternalWindow title="User Form" width={600} height={500} centerScreen="both" onClose={handleClose}>
-          <Form onFinish={handleSubmit} style={{ padding: 20 }}>
-            <Form.Item name="name" label="Name">
-              <Input />
-            </Form.Item>
-            <Form.Item>
-              <Button type="primary" htmlType="submit">
-                Submit
-              </Button>
-            </Form.Item>
-          </Form>
-        </ExternalWindow>
-      )}
-    </>
-  );
-}
-```
-
-## Browser Compatibility
-
-| Browser       | Support    | Notes                            |
-| ------------- | ---------- | -------------------------------- |
-| Chrome/Edge   | ✅ Full    | Recommended                      |
-| Firefox       | ✅ Full    | All features work                |
-| Safari        | ✅ Full    | All features work                |
-| Mobile Safari | ⚠️ Limited | Popup windows not well supported |
-| Mobile Chrome | ⚠️ Limited | Popup windows not well supported |
-
-**Note**: Mobile browsers have limited support for popup windows due to platform restrictions.
-
-## Troubleshooting
-
-### Issue: Window flickering or re-rendering constantly
-
-**Symptoms:**
-
-- Window content flickers
-- Continuous re-renders
-- Poor performance
-
-**Cause:** The `onClose` callback is not memoized, creating a new function reference on every render.
-
-**Solution:**
-
-```jsx
-// ❌ Wrong - creates new function every render
-<ExternalWindow onClose={() => setShowWindow(false)}>
-
-// ✅ Correct - stable function reference
-const handleClose = useCallback(() => setShowWindow(false), []);
-<ExternalWindow onClose={handleClose}>
-```
-
----
-
-### Issue: Window not opening / "Please allow popups" message
-
-**Symptoms:**
-
-- Error message appears
-- Window doesn't open
-- `window.open()` returns `null`
-
-**Cause:** Browser popup blocker is active.
-
-**Solution:**
-
-1. Click the popup blocker icon in the browser's address bar
-2. Allow popups for your site
-3. Refresh the page and try again
-
-**Prevention:** Always trigger `ExternalWindow` from a user action (click, keyboard event), not automatically on page load.
-
----
-
-### Issue: Styles not appearing correctly
-
-**Symptoms:**
-
-- Missing Ant Design styles
-- SCSS not applied
-- Different appearance from parent window
-
-**Cause:**
-
-- `copyStyles={false}` is set
-- Cross-origin stylesheet restrictions (CORS)
-- Styles loaded after component initialization
-
-**Solution:**
-
-```jsx
-// Ensure copyStyles is true (default)
-<ExternalWindow copyStyles={true} ... />
-
-// Check browser console for CORS warnings
-// Allow time for async style loading
-```
-
----
-
-### Issue: White flash when opening window
-
-**Status:** ✅ **Fixed in current version**
-
-The component now includes critical inline styles that apply immediately, inheriting the parent window's background color. Full styles load asynchronously without blocking.
-
-If you still see a white flash:
-
-- Ensure you're using the latest version of the component
-- Check that `copyStyles={true}` (default)
-- Verify your parent window has a defined background color
-
----
-
-### Issue: Unexpected body spacing or margins
-
-**Symptoms:**
-
-- Unwanted whitespace around content
-- Incorrect layout
-- Content not filling window
-
-**Cause:** Browser default styles or inherited styles.
-
-**Solution:** The component applies aggressive CSS resets:
-
-```css
-html,
-body {
-  margin: 0 !important;
-  padding: 0 !important;
-  width: 100%;
-  height: 100%;
-}
-```
-
-If you need custom body styles, apply them to your content wrapper:
-
-```jsx
-<ExternalWindow ...>
-  <div style={{ padding: 20, background: '#f0f0f0' }}>
-    Your content here
-  </div>
-</ExternalWindow>
-```
-
----
-
-### Issue: Keyboard shortcuts not working
-
-**Symptoms:**
-
-- Pressing shortcut keys doesn't trigger actions
-- Only works in parent window
-
-**Cause:**
-
-- Window doesn't have focus
-- Shortcut conflicts with browser defaults
-- Incorrect shortcut format
-
-**Solution:**
-
-```jsx
-// Correct format
-shortcuts={{
-  close: 'Escape',
-  focus: 'Ctrl+Shift+F',  // Not 'Control+Shift+F'
-  save: 'Ctrl+S'
-}}
-
-// Use focus shortcut to bring window to front
-// Avoid browser shortcuts (Ctrl+T, Ctrl+W, etc.)
-```
-
----
-
-### Issue: Multiple windows interfere with each other
-
-**Symptoms:**
-
-- Opening one window closes another
-- State conflicts between windows
-
-**Cause:** Poor state management or shared state keys.
-
-**Solution:**
-
-```jsx
-// Use unique keys and separate state
-const [windows, setWindows] = useState({});
-
-const openWindow = (id) => {
-  setWindows((prev) => ({ ...prev, [id]: true }));
-};
-
-const closeWindow = (id) => {
-  setWindows((prev) => {
-    const updated = { ...prev };
-    delete updated[id];
-    return updated;
-  });
-};
-```
-
----
-
-### Issue: Content not updating in external window
-
-**Symptoms:**
-
-- Changes in parent don't reflect in child window
-- Stale data displayed
-
-**Cause:** React Portal works correctly, but state might not be lifting properly.
-
-**Solution:** React Portal automatically syncs state. Ensure your state is at the correct level:
-
-```jsx
-// State should be in parent component
-const [data, setData] = useState([]);
-
-<ExternalWindow ...>
-  <DataDisplay data={data} onChange={setData} />
-</ExternalWindow>
-```
-
----
-
-### Issue: Window closes unexpectedly
-
-**Symptoms:**
-
-- Window closes on its own
-- Window closes when clicking parent
-
-**Cause:**
-
-- User closed the window (triggers `onClose`)
-- Parent component unmounted
-- State management issue
-
-**Solution:** This is expected behavior. The `onClose` callback is triggered when:
-
-- User clicks the window's close button
-- User presses the close keyboard shortcut
-- Component unmounts
-- Parent explicitly calls the close handler
-
----
-
-### Issue: Cross-origin stylesheet warnings in console
-
-**Symptoms:**
-
-- Console warnings: "Could not copy stylesheet"
-- Some styles missing
-
-**Cause:** CORS restrictions prevent accessing external stylesheet rules.
-
-**Solution:** This is expected and usually not a problem:
-
-- External stylesheets (CDNs) are copied by `<link>` reference
-- Only inline style rules require CORS access
-- Most styles will still work correctly
-
-To debug:
-
-```javascript
-// The component logs warnings for debugging
-console.warn('Could not copy stylesheet:', e);
-```
-
----
-
-## Getting Help
-
-If you encounter issues not covered here:
-
-1. Check the browser console for errors
-2. Verify all props are correctly typed
-3. Ensure `useCallback` is used for callbacks
-4. Test in a different browser
-5. Check for popup blocker settings
-
-## License
-
-MIT
+# ExternalWindow Component
+
+A React component that renders content in a separate browser window with full style inheritance and keyboard shortcuts support.
+
+## Features
+
+- 🪟 Opens content in a new browser window
+- 🎨 Automatically copies parent window styles (Ant Design, SCSS, etc.)
+- ⚨️ Customizable keyboard shortcuts
+- 📍 Flexible positioning (manual or auto-center)
+- 🔄 React Portal-based rendering
+- ⚡ No white flash - instant background color matching
+- 🧹 Automatic cleanup on unmount
+
+## Quick Start
+
+```jsx
+import { useState, useCallback } from 'react';
+import { ExternalWindow } from './ExternalWindow';
+import { Button } from 'antd';
+
+function App() {
+  const [showWindow, setShowWindow] = useState(false);
+
+  // Use useCallback to prevent re-renders
+  const handleClose = useCallback(() => {
+    setShowWindow(false);
+  }, []);
+
+  return (
+    <>
+      <Button onClick={() => setShowWindow(true)}>Open New Window</Button>
+
+      {showWindow && (
+        <ExternalWindow title="My External Window" onClose={handleClose}>
+          <div style={{ padding: 20 }}>
+            <h1>Hello from external window!</h1>
+            <p>All your styles are automatically copied here.</p>
+          </div>
+        </ExternalWindow>
+      )}
+    </>
+  );
+}
+```
+
+## Props Reference
+
+### Props
+
+| Prop           | Type            | Default                                      | Description                                                       |
+| -------------- | --------------- | -------------------------------------------- | ----------------------------------------------------------------- |
+| `children`     | `ReactNode`     | **required**                                 | Content to render in the new window                               |
+| `onClose`      | `Function`      | **required**                                 | Callback when window closes (wrap in `useCallback`)               |
+| `title`        | `string`        | `'New Window'`                               | Window title (shown in browser tab)                               |
+| `width`        | `number`        | `600`                                        | Window width in pixels                                            |
+| `height`       | `number`        | `400`                                        | Window height in pixels                                           |
+| `left`         | `number`        | `200`                                        | Window X position (overridden by `centerScreen`)                  |
+| `top`          | `number`        | `200`                                        | Window Y position (overridden by `centerScreen`)                  |
+| `copyStyles`   | `boolean`       | `true`                                       | Whether to copy parent window styles                              |
+| `centerScreen` | `string\|false` | `false`                                      | Center window: `'horizontal'`, `'vertical'`, `'both'`, or `false` |
+| `shortcuts`    | `Object`        | `{ close: 'Escape', focus: 'Ctrl+Shift+F' }` | Keyboard shortcuts configuration                                  |
+| `onMinimize`   | `Function`      | `undefined`                                  | Callback when window is minimized                                 |
+| `onMaximize`   | `Function`      | `undefined`                                  | Callback when window is maximized                                 |
+
+## Usage Examples
+
+### Centered Window
+
+```jsx
+import { useState, useCallback } from 'react';
+
+function App() {
+  const [showWindow, setShowWindow] = useState(false);
+
+  const handleClose = useCallback(() => {
+    setShowWindow(false);
+  }, []);
+
+  return (
+    <>
+      <Button onClick={() => setShowWindow(true)}>Open Centered</Button>
+
+      {showWindow && (
+        <ExternalWindow title="Centered Window" width={800} height={600} centerScreen="both" onClose={handleClose}>
+          <YourContent />
+        </ExternalWindow>
+      )}
+    </>
+  );
+}
+```
+
+### Custom Positioning
+
+```jsx
+const handleClose = useCallback(() => setShowWindow(false), []);
+
+<ExternalWindow title="Custom Position" width={1000} height={700} left={100} top={50} onClose={handleClose}>
+  <YourContent />
+</ExternalWindow>;
+```
+
+### With Custom Keyboard Shortcuts
+
+```jsx
+const handleClose = useCallback(() => setShowWindow(false), []);
+const handleMinimize = useCallback(() => console.log('Minimized'), []);
+const handleMaximize = useCallback(() => console.log('Maximized'), []);
+
+<ExternalWindow
+  title="With Shortcuts"
+  shortcuts={{
+    close: 'Escape', // Close window
+    focus: 'Ctrl+Shift+F', // Focus window
+    minimize: 'Ctrl+M', // Minimize window
+    maximize: 'Ctrl+Shift+M', // Maximize window
+  }}
+  onClose={handleClose}
+  onMinimize={handleMinimize}
+  onMaximize={handleMaximize}
+>
+  <YourContent />
+</ExternalWindow>;
+```
+
+### Without Style Copying
+
+```jsx
+const handleClose = useCallback(() => setShowWindow(false), []);
+
+<ExternalWindow title="No Styles" copyStyles={false} onClose={handleClose}>
+  {/* You'll need to add inline styles or external CSS links */}
+  <div style={{ padding: 20, fontFamily: 'Arial' }}>
+    <h1>Plain content</h1>
+  </div>
+</ExternalWindow>;
+```
+
+### Managing Multiple Windows
+
+```jsx
+function MultiWindowApp() {
+  const [windows, setWindows] = useState([]);
+
+  const openWindow = useCallback((config) => {
+    const id = Date.now();
+    setWindows((prev) => [...prev, { id, ...config }]);
+  }, []);
+
+  const closeWindow = useCallback((id) => {
+    setWindows((prev) => prev.filter((w) => w.id !== id));
+  }, []);
+
+  return (
+    <>
+      <Button
+        onClick={() =>
+          openWindow({
+            title: 'Window ' + (windows.length + 1),
+            content: <MyComponent />,
+          })
+        }
+      >
+        Add Window
+      </Button>
+
+      {windows.map(({ id, title, content }) => (
+        <ExternalWindow key={id} title={title} onClose={() => closeWindow(id)}>
+          {content}
+        </ExternalWindow>
+      ))}
+    </>
+  );
+}
+```
+
+### Full-Featured Dashboard Example
+
+```jsx
+import { useState, useCallback } from 'react';
+import { ExternalWindow } from './ExternalWindow';
+import { Button, Card, Space } from 'antd';
+
+function Dashboard() {
+  const [windows, setWindows] = useState({
+    chart: false,
+    report: false,
+    settings: false,
+  });
+
+  const openWindow = useCallback((name) => {
+    setWindows((prev) => ({ ...prev, [name]: true }));
+  }, []);
+
+  const closeWindow = useCallback((name) => {
+    setWindows((prev) => ({ ...prev, [name]: false }));
+  }, []);
+
+  return (
+    <div style={{ padding: 24 }}>
+      <Space>
+        <Button onClick={() => openWindow('chart')}>Open Chart</Button>
+        <Button onClick={() => openWindow('report')}>Open Report</Button>
+        <Button onClick={() => openWindow('settings')}>Open Settings</Button>
+      </Space>
+
+      {windows.chart && (
+        <ExternalWindow title="Analytics Chart" width={1200} height={800} centerScreen="both" onClose={() => closeWindow('chart')}>
+          <Card title="Sales Analytics" style={{ margin: 20 }}>
+            {/* Your chart component */}
+          </Card>
+        </ExternalWindow>
+      )}
+
+      {windows.report && (
+        <ExternalWindow title="Monthly Report" width={900} height={700} left={50} top={50} onClose={() => closeWindow('report')}>
+          <div style={{ padding: 20 }}>{/* Your report component */}</div>
+        </ExternalWindow>
+      )}
+
+      {windows.settings && (
+        <ExternalWindow
+          title="Settings"
+          width={600}
+          height={500}
+          centerScreen="horizontal"
+          shortcuts={{
+            close: 'Escape',
+            focus: 'Ctrl+S',
+          }}
+          onClose={() => closeWindow('settings')}
+        >
+          <div style={{ padding: 20 }}>{/* Your settings component */}</div>
+        </ExternalWindow>
+      )}
+    </div>
+  );
+}
+```
+
+### With Shared State
+
+```jsx
+function StatefulWindow() {
+  const [showWindow, setShowWindow] = useState(false);
+  const [data, setData] = useState([]);
+
+  const handleClose = useCallback(() => {
+    setShowWindow(false);
+  }, []);
+
+  return (
+    <>
+      <Button onClick={() => setShowWindow(true)}>Open Data Viewer</Button>
+
+      {showWindow && (
+        <ExternalWindow title="Data Viewer" onClose={handleClose}>
+          {/* State is shared between parent and child window */}
+          <DataTable data={data} onUpdate={setData} />
+        </ExternalWindow>
+      )}
+    </>
+  );
+}
+```
+
+## Keyboard Shortcuts
+
+### Default Shortcuts
+
+- **Escape**: Close window
+- **Ctrl+Shift+F**: Focus window
+
+### Customizing Shortcuts
+
+Define custom shortcuts using the `shortcuts` prop. Shortcuts support modifiers:
+
+- `Ctrl` / `Control`
+- `Shift`
+- `Alt`
+- `Meta` (Command on Mac)
+
+**Format Examples:**
+
+```javascript
+shortcuts={{
+  close: 'Escape',
+  focus: 'Ctrl+Shift+F',
+  minimize: 'Ctrl+M',
+  maximize: 'Ctrl+Shift+M',
+  save: 'Ctrl+S',
+  custom: 'Alt+K'
+}}
+```
+
+## How It Works
+
+### Style Inheritance
+
+When `copyStyles={true}` (default):
+
+1. **Instant Background**: Critical inline styles are applied immediately, inheriting the parent window's background color and text color
+2. **No White Flash**: The window opens with proper styling from the start
+3. **Async Loading**: Full stylesheets are copied asynchronously for smooth rendering
+4. **Complete Coverage**: All parent window styles are copied:
+   - Ant Design themes
+   - SCSS/CSS modules
+   - Custom fonts
+   - External stylesheets
+   - Inline styles
+
+### Window Lifecycle
+
+1. Window opens with specified dimensions and position
+2. Critical styles applied instantly (background, colors, layout)
+3. Full styles copied from parent window
+4. Content rendered via React Portal
+5. Event listeners attached (keyboard shortcuts, window close)
+6. Automatic cleanup on component unmount
+
+### Performance Optimizations
+
+- **Single Window Creation**: Window is created once and reused throughout component lifecycle
+- **Async Style Loading**: Styles are copied using `requestAnimationFrame` to avoid blocking
+- **Stable References**: Uses `useCallback` and `useMemo` to prevent unnecessary re-renders
+- **Efficient Cleanup**: Proper event listener removal and window closure
+
+## Best Practices
+
+### ✅ Do's
+
+```jsx
+// Use useCallback for all callbacks
+const handleClose = useCallback(() => setShowWindow(false), []);
+const handleMinimize = useCallback(() => console.log('Min'), []);
+
+// Center important windows
+<ExternalWindow centerScreen="both" ... />
+
+// Provide meaningful titles
+<ExternalWindow title="Sales Report - Q4 2024" ... />
+
+// Use appropriate dimensions
+<ExternalWindow width={1200} height={800} ... />
+```
+
+### ❌ Don'ts
+
+```jsx
+// Don't use inline functions - causes re-renders
+<ExternalWindow onClose={() => setShowWindow(false)} ... />
+
+// Don't forget to handle window state
+{showWindow && <ExternalWindow ... />}
+
+// Don't use tiny dimensions
+<ExternalWindow width={100} height={100} ... />
+
+// Don't disable style copying without reason
+<ExternalWindow copyStyles={false} ... />
+```
+
+## Advanced Patterns
+
+### Window with Tabs
+
+```jsx
+function TabbedWindow() {
+  const [showWindow, setShowWindow] = useState(false);
+  const [activeTab, setActiveTab] = useState('1');
+
+  const handleClose = useCallback(() => setShowWindow(false), []);
+
+  return (
+    <>
+      <Button onClick={() => setShowWindow(true)}>Open</Button>
+
+      {showWindow && (
+        <ExternalWindow title="Multi-Tab Window" width={1000} height={700} centerScreen="both" onClose={handleClose}>
+          <Tabs activeKey={activeTab} onChange={setActiveTab}>
+            <TabPane tab="Dashboard" key="1">
+              <Dashboard />
+            </TabPane>
+            <TabPane tab="Settings" key="2">
+              <Settings />
+            </TabPane>
+            <TabPane tab="Reports" key="3">
+              <Reports />
+            </TabPane>
+          </Tabs>
+        </ExternalWindow>
+      )}
+    </>
+  );
+}
+```
+
+### Window with Form Submission
+
+```jsx
+function FormWindow() {
+  const [showWindow, setShowWindow] = useState(false);
+
+  const handleClose = useCallback(() => setShowWindow(false), []);
+
+  const handleSubmit = useCallback((values) => {
+    console.log('Form submitted:', values);
+    setShowWindow(false);
+  }, []);
+
+  return (
+    <>
+      <Button onClick={() => setShowWindow(true)}>Open Form</Button>
+
+      {showWindow && (
+        <ExternalWindow title="User Form" width={600} height={500} centerScreen="both" onClose={handleClose}>
+          <Form onFinish={handleSubmit} style={{ padding: 20 }}>
+            <Form.Item name="name" label="Name">
+              <Input />
+            </Form.Item>
+            <Form.Item>
+              <Button type="primary" htmlType="submit">
+                Submit
+              </Button>
+            </Form.Item>
+          </Form>
+        </ExternalWindow>
+      )}
+    </>
+  );
+}
+```
+
+## Browser Compatibility
+
+| Browser       | Support    | Notes                            |
+| ------------- | ---------- | -------------------------------- |
+| Chrome/Edge   | ✅ Full    | Recommended                      |
+| Firefox       | ✅ Full    | All features work                |
+| Safari        | ✅ Full    | All features work                |
+| Mobile Safari | ⚠️ Limited | Popup windows not well supported |
+| Mobile Chrome | ⚠️ Limited | Popup windows not well supported |
+
+**Note**: Mobile browsers have limited support for popup windows due to platform restrictions.
+
+## Troubleshooting
+
+### Issue: Window flickering or re-rendering constantly
+
+**Symptoms:**
+
+- Window content flickers
+- Continuous re-renders
+- Poor performance
+
+**Cause:** The `onClose` callback is not memoized, creating a new function reference on every render.
+
+**Solution:**
+
+```jsx
+// ❌ Wrong - creates new function every render
+<ExternalWindow onClose={() => setShowWindow(false)}>
+
+// ✅ Correct - stable function reference
+const handleClose = useCallback(() => setShowWindow(false), []);
+<ExternalWindow onClose={handleClose}>
+```
+
+---
+
+### Issue: Window not opening / "Please allow popups" message
+
+**Symptoms:**
+
+- Error message appears
+- Window doesn't open
+- `window.open()` returns `null`
+
+**Cause:** Browser popup blocker is active.
+
+**Solution:**
+
+1. Click the popup blocker icon in the browser's address bar
+2. Allow popups for your site
+3. Refresh the page and try again
+
+**Prevention:** Always trigger `ExternalWindow` from a user action (click, keyboard event), not automatically on page load.
+
+---
+
+### Issue: Styles not appearing correctly
+
+**Symptoms:**
+
+- Missing Ant Design styles
+- SCSS not applied
+- Different appearance from parent window
+
+**Cause:**
+
+- `copyStyles={false}` is set
+- Cross-origin stylesheet restrictions (CORS)
+- Styles loaded after component initialization
+
+**Solution:**
+
+```jsx
+// Ensure copyStyles is true (default)
+<ExternalWindow copyStyles={true} ... />
+
+// Check browser console for CORS warnings
+// Allow time for async style loading
+```
+
+---
+
+### Issue: White flash when opening window
+
+**Status:** ✅ **Fixed in current version**
+
+The component now includes critical inline styles that apply immediately, inheriting the parent window's background color. Full styles load asynchronously without blocking.
+
+If you still see a white flash:
+
+- Ensure you're using the latest version of the component
+- Check that `copyStyles={true}` (default)
+- Verify your parent window has a defined background color
+
+---
+
+### Issue: Unexpected body spacing or margins
+
+**Symptoms:**
+
+- Unwanted whitespace around content
+- Incorrect layout
+- Content not filling window
+
+**Cause:** Browser default styles or inherited styles.
+
+**Solution:** The component applies aggressive CSS resets:
+
+```css
+html,
+body {
+  margin: 0 !important;
+  padding: 0 !important;
+  width: 100%;
+  height: 100%;
+}
+```
+
+If you need custom body styles, apply them to your content wrapper:
+
+```jsx
+<ExternalWindow ...>
+  <div style={{ padding: 20, background: '#f0f0f0' }}>
+    Your content here
+  </div>
+</ExternalWindow>
+```
+
+---
+
+### Issue: Keyboard shortcuts not working
+
+**Symptoms:**
+
+- Pressing shortcut keys doesn't trigger actions
+- Only works in parent window
+
+**Cause:**
+
+- Window doesn't have focus
+- Shortcut conflicts with browser defaults
+- Incorrect shortcut format
+
+**Solution:**
+
+```jsx
+// Correct format
+shortcuts={{
+  close: 'Escape',
+  focus: 'Ctrl+Shift+F',  // Not 'Control+Shift+F'
+  save: 'Ctrl+S'
+}}
+
+// Use focus shortcut to bring window to front
+// Avoid browser shortcuts (Ctrl+T, Ctrl+W, etc.)
+```
+
+---
+
+### Issue: Multiple windows interfere with each other
+
+**Symptoms:**
+
+- Opening one window closes another
+- State conflicts between windows
+
+**Cause:** Poor state management or shared state keys.
+
+**Solution:**
+
+```jsx
+// Use unique keys and separate state
+const [windows, setWindows] = useState({});
+
+const openWindow = (id) => {
+  setWindows((prev) => ({ ...prev, [id]: true }));
+};
+
+const closeWindow = (id) => {
+  setWindows((prev) => {
+    const updated = { ...prev };
+    delete updated[id];
+    return updated;
+  });
+};
+```
+
+---
+
+### Issue: Content not updating in external window
+
+**Symptoms:**
+
+- Changes in parent don't reflect in child window
+- Stale data displayed
+
+**Cause:** React Portal works correctly, but state might not be lifting properly.
+
+**Solution:** React Portal automatically syncs state. Ensure your state is at the correct level:
+
+```jsx
+// State should be in parent component
+const [data, setData] = useState([]);
+
+<ExternalWindow ...>
+  <DataDisplay data={data} onChange={setData} />
+</ExternalWindow>
+```
+
+---
+
+### Issue: Window closes unexpectedly
+
+**Symptoms:**
+
+- Window closes on its own
+- Window closes when clicking parent
+
+**Cause:**
+
+- User closed the window (triggers `onClose`)
+- Parent component unmounted
+- State management issue
+
+**Solution:** This is expected behavior. The `onClose` callback is triggered when:
+
+- User clicks the window's close button
+- User presses the close keyboard shortcut
+- Component unmounts
+- Parent explicitly calls the close handler
+
+---
+
+### Issue: Cross-origin stylesheet warnings in console
+
+**Symptoms:**
+
+- Console warnings: "Could not copy stylesheet"
+- Some styles missing
+
+**Cause:** CORS restrictions prevent accessing external stylesheet rules.
+
+**Solution:** This is expected and usually not a problem:
+
+- External stylesheets (CDNs) are copied by `<link>` reference
+- Only inline style rules require CORS access
+- Most styles will still work correctly
+
+To debug:
+
+```javascript
+// The component logs warnings for debugging
+console.warn('Could not copy stylesheet:', e);
+```
+
+---
+
+## Getting Help
+
+If you encounter issues not covered here:
+
+1. Check the browser console for errors
+2. Verify all props are correctly typed
+3. Ensure `useCallback` is used for callbacks
+4. Test in a different browser
+5. Check for popup blocker settings
+
+## License
+
+MIT