ui-soxo-bootstrap-core 2.4.25 → 2.5.0

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

@@ -0,0 +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