@dimetrix/react-iframe - npm Package Compare versions

Comparing version 1.0.0 to 1.0.1

package.json

 {
   "name": "@dimetrix/react-iframe",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A fully configurable React component that renders React components inside an isolated iframe",
@@ -5,0 +5,0 @@ "type": "module",

README.md

@@ -7,18 +7,27 @@ # React Iframe
 
+[![npm version](https://img.shields.io/npm/v/@dimetrix/react-iframe.svg)](https://www.npmjs.com/package/@dimetrix/react-iframe)
+[![npm downloads](https://img.shields.io/npm/dm/@dimetrix/react-iframe.svg)](https://www.npmjs.com/package/@dimetrix/react-iframe)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
 [![React](https://img.shields.io/badge/React-17%20%7C%2018%20%7C%2019-61dafb.svg)](https://react.dev/)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@dimetrix/react-iframe)](https://bundlephobia.com/package/@dimetrix/react-iframe)
 
+[Documentation](#-documentation) • [Examples](#-usage-examples) • [Installation](#-installation) • [Contributing](#-contributing)
+
 </div>
 
+---
+
 ## ✨ Features
 
-- 🎯 **Full React Support** - All React features work normally (hooks, state, effects, context)
-- 🎨 **Style Isolation** - CSS is scoped to the iframe, preventing style conflicts with parent page
+- 🎯 **Full React Support** - All React features work normally (hooks, state, effects, context, suspense)
+- 🎨 **Complete Style Isolation** - CSS is scoped to the iframe, preventing style conflicts with parent page
+- 📏 **Auto Height** - Automatically adjust iframe height to match content (no scrollbars, enabled by default)
 - 🔧 **Complete iframe API** - All standard HTML iframe attributes and events are supported
-- 📏 **Auto Height** - Automatically adjust iframe height to match content (no scrollbars)
-- 💪 **TypeScript** - Full type safety with proper iframe prop types
+- 💪 **TypeScript** - Full type safety with proper iframe prop types and IntelliSense support
 - 🎭 **Flexible API** - Accept components as children or via `component` prop
-- ♿ **Accessibility** - All ARIA attributes supported
-- ⚡ **Performance** - Optimized with React best practices (memo, useMemo, useCallback)
+- ♿ **Accessibility** - All ARIA attributes and accessibility features supported
+- ⚡ **Performance Optimized** - Built with React best practices (memo, useMemo, useCallback)
+- 🎨 **Tailwind CSS Ready** - Tailwind CSS is automatically injected into the iframe for styling
+- 🔒 **Security** - Full support for sandbox attributes and security policies
 
@@ -48,3 +57,2 @@ ## 📦 Installation
       width="100%"
-      height="400px"
       sandbox="allow-scripts allow-same-origin"
@@ -56,2 +64,4 @@ />
 
+> **Note:** `autoHeight` is enabled by default, so no `height` prop is needed. The iframe will automatically adjust to match its content height.
+
 ### Using Children
@@ -71,4 +81,2 @@
 
-> **Note:** `autoHeight` is enabled by default, so no `height` prop is needed.
-
 ## 📖 Documentation
@@ -88,28 +96,38 @@
 | `maxHeight` | `number` | `undefined` | Maximum height in pixels when `autoHeight` is enabled |
-| `...iframeProps` | `React.IframeHTMLAttributes` | - | All standard HTML iframe attributes |
+| `...iframeProps` | `React.IframeHTMLAttributes` | - | All standard HTML iframe attributes (see below) |
 
-> **Note:** Either `component` or `children` must be provided, but not both.
+> **Important:** Either `component` or `children` must be provided, but not both.
 
 ### Standard Iframe Attributes
 
-All standard HTML iframe attributes are supported and passed through:
+All standard HTML iframe attributes are supported and passed through to the underlying iframe element:
 
-**Common Attributes:**
-- `sandbox` - Security sandbox attributes (e.g., `"allow-scripts allow-same-origin"`)
-- `allow` - Feature policy (e.g., `"camera; microphone; geolocation"`)
-- `allowFullScreen` - Allow fullscreen mode
-- `referrerPolicy` - Referrer policy (`"no-referrer"`, `"strict-origin-when-cross-origin"`, etc.)
-- `loading` - Lazy loading (`"lazy"` or `"eager"`)
-- `name` - Frame name
-- `width`, `height` - Dimensions (ignored when `autoHeight` is `true`)
-- `title` - Accessibility title
-- `className`, `style` - Styling
+#### Common Attributes
 
-**Event Handlers:**
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `sandbox` | `string` | Security sandbox attributes (e.g., `"allow-scripts allow-same-origin"`) |
+| `allow` | `string` | Feature policy (e.g., `"camera; microphone; geolocation"`) |
+| `allowFullScreen` | `boolean` | Allow fullscreen mode |
+| `referrerPolicy` | `string` | Referrer policy (`"no-referrer"`, `"strict-origin-when-cross-origin"`, etc.) |
+| `loading` | `"lazy" \| "eager"` | Lazy loading behavior |
+| `name` | `string` | Frame name for targeting |
+| `width` | `string \| number` | Width (ignored when `autoHeight` is `true`) |
+| `height` | `string \| number` | Height (ignored when `autoHeight` is `true`) |
+| `title` | `string` | Accessibility title |
+| `className` | `string` | CSS class name |
+| `style` | `CSSProperties` | Inline styles |
+
+#### Event Handlers
+
+All standard React event handlers are supported:
+
 - `onLoad` - Fired when iframe loads
 - `onError` - Fired on iframe error
 - `onFocus`, `onBlur` - Focus events
-- All other standard React event handlers
+- `onMouseEnter`, `onMouseLeave` - Mouse events
+- And all other standard React event handlers
 
-**Data & ARIA Attributes:**
+#### Data & ARIA Attributes
+
 - All `data-*` attributes
@@ -131,3 +149,2 @@ - All `aria-*` attributes
       width="100%"
-      height="300px"
       sandbox="allow-scripts allow-same-origin"
@@ -156,3 +173,2 @@ title="Counter Component"
       width="100%"
-      height="500px"
     />
@@ -163,3 +179,3 @@ );
 
-### Example 3: Auto Height (Responsive)
+### Example 3: Auto Height with Constraints
 
@@ -186,3 +202,3 @@ ```tsx
 
-### Example 4: Advanced Configuration
+### Example 4: Disabling Auto Height
 
@@ -194,2 +210,21 @@ ```tsx
 function App() {
+  return (
+    <ReactIframe
+      component={MyComponent}
+      width="100%"
+      height="400px"
+      autoHeight={false}
+      sandbox="allow-scripts allow-same-origin"
+    />
+  );
+}
+```
+
+### Example 5: Advanced Configuration
+
+```tsx
+import { ReactIframe } from '@dimetrix/react-iframe';
+import MyComponent from './MyComponent';
+
+function App() {
   const handleLoad = (event: React.SyntheticEvent<HTMLIFrameElement>) => {
@@ -224,3 +259,3 @@ console.log('Iframe loaded successfully', event);
 
-### Example 5: Using Children with Render Props
+### Example 6: Using Children with Tailwind CSS
 
@@ -232,9 +267,33 @@ ```tsx
   return (
+    <ReactIframe width="100%">
+      <div className="p-4 bg-blue-500 text-white rounded-lg">
+        <h1 className="text-2xl font-bold">Hello from iframe!</h1>
+        <p className="mt-2">Tailwind CSS works automatically inside the iframe.</p>
+      </div>
+    </ReactIframe>
+  );
+}
+```
+
+Tailwind CSS is automatically injected into the iframe, so you can use Tailwind utility classes directly in your components.
+
+### Example 7: Dynamic Content with State
+
+```tsx
+import { useState } from 'react';
+import { ReactIframe } from '@dimetrix/react-iframe';
+import Counter from './Counter';
+
+function App() {
+  const [count, setCount] = useState(0);
+
+  return (
     <ReactIframe
+      component={Counter}
+      componentProps={{ 
+        initialCount: count,
+        onCountChange: setCount 
+      }}
       width="100%"
-      height="400px"
-      componentProps={{ initialCount: 10 }}
-    >
-      {(props) => <Counter initialCount={props.initialCount} />}
-    </ReactIframe>
+    />
   );
@@ -247,7 +306,15 @@ }
 1. **Iframe Creation**: The component creates an iframe element with your specified attributes
-2. **Document Setup**: Sets up the iframe's document structure with basic HTML and styles
+2. **Document Setup**: Sets up the iframe's document structure with basic HTML, Tailwind CSS, and styles
 3. **React Rendering**: Uses the parent window's ReactDOM to render your component into the iframe
 4. **Style Isolation**: All styles are scoped to the iframe, preventing conflicts with the parent page
-5. **Auto Height** (if enabled): Uses `ResizeObserver` and `MutationObserver` to detect content size changes and adjust the iframe height accordingly
+5. **Auto Height** (if enabled): Uses `ResizeObserver` and `MutationObserver` to detect content size changes and adjust the iframe height accordingly with `requestAnimationFrame` throttling for optimal performance
 
+### Technical Details
+
+- **React Mounting**: Uses `ReactDOM.createRoot` to mount React components into the iframe's document
+- **Style Injection**: Tailwind CSS is automatically injected via CDN into the iframe's `<head>`
+- **Height Calculation**: Auto-height uses computed styles to account for margins and padding, ensuring accurate measurements
+- **Performance**: Observers are throttled using `requestAnimationFrame` to minimize performance impact
+- **Cleanup**: All observers and event listeners are properly cleaned up when the component unmounts
+
 ## 🎯 Common Use Cases
@@ -258,11 +325,42 @@
 
+```tsx
+<ReactIframe
+  component={MyWidget}
+  width="100%"
+  sandbox="allow-scripts allow-same-origin"
+/>
+```
+
 ### Component Sandboxing
 Test or preview components in isolation without affecting the parent application.
 
+```tsx
+<ReactIframe
+  component={ComponentToTest}
+  width="100%"
+  sandbox="allow-scripts allow-same-origin"
+/>
+```
+
 ### Style Isolation
 Render components with their own CSS that won't interfere with the parent page styles.
 
+```tsx
+<ReactIframe width="100%">
+  <StyledComponent />
+</ReactIframe>
+```
+
 ### Dynamic Content
 Display content that changes size dynamically with automatic height adjustment.
 
+```tsx
+<ReactIframe
+  component={DynamicContent}
+  width="100%"
+  minHeight={200}
+  maxHeight={1000}
+/>
+```
+
 ## 🛠️ TypeScript
@@ -279,5 +377,9 @@
   width: '100%',
-  height: '400px',
   autoHeight: true,
 };
+
+// Type-safe component
+function MyApp() {
+  return <ReactIframe {...props} />;
+}
 ```
@@ -288,2 +390,3 @@
 Works in all modern browsers that support:
+
 - React 17, 18, or 19
@@ -294,2 +397,11 @@ - HTML5 iframes
 
+### Browser Compatibility
+
+| Browser | Version |
+|---------|---------|
+| Chrome | 64+ |
+| Firefox | 69+ |
+| Safari | 13.1+ |
+| Edge | 79+ |
+
 ## 📚 Examples
@@ -301,3 +413,3 @@
 2. **Form Component** - Shows user interaction and form handling
-3. **Styled Box Component** - Illustrates CSS isolation
+3. **Styled Box Component** - Illustrates CSS isolation and Tailwind CSS usage
 
@@ -322,3 +434,3 @@ To run the example:
 
-// ❌ May not work - too restrictive
+// ❌ May not work - too restrictive for auto-height
 sandbox="allow-scripts"
@@ -330,4 +442,5 @@ ```
 - Auto-height requires access to the iframe's content, so ensure `sandbox` includes `allow-same-origin` if used
-- The feature uses `ResizeObserver` with a fallback to polling for older browsers
-- Performance is optimized with `requestAnimationFrame` throttling
+- The feature uses `ResizeObserver` with optimized `requestAnimationFrame` throttling
+- Performance is optimized to minimize reflows and repaints
+- Height calculation accounts for margins and padding automatically
 
@@ -339,3 +452,11 @@ ### Component Props
 - Changes to `componentProps` will trigger re-renders inside the iframe
+- Props are compared using shallow equality, so use memoization for complex objects
 
+### Style Isolation
+
+- All styles are isolated within the iframe
+- Tailwind CSS is automatically available via CDN
+- Custom CSS can be injected programmatically if needed
+- CSS variables can be passed through for theming
+
 ## 🐛 Troubleshooting
@@ -347,12 +468,23 @@
 
-1. Check your `sandbox` attribute - ensure `allow-same-origin` is included
-2. Verify CORS settings if loading from a different origin
-3. Check browser console for specific error messages
+1. **Check your `sandbox` attribute** - Ensure `allow-same-origin` is included:
+   ```tsx
+   sandbox="allow-scripts allow-same-origin"
+   ```
 
+2. **Verify CORS settings** - If loading from a different origin, check CORS headers
+
+3. **Check browser console** - Look for specific error messages
+
 ### Auto-height not working
 
-1. Ensure `autoHeight={true}` is set
-2. Verify `sandbox` includes `allow-same-origin`
-3. Check that content is actually changing size
-4. Try setting explicit `minHeight` to see if the feature is working
+1. **Ensure `autoHeight={true}`** is set (it's the default)
+2. **Verify `sandbox` includes `allow-same-origin`**:
+   ```tsx
+   sandbox="allow-scripts allow-same-origin"
+   ```
+3. **Check that content is actually changing size** - Use browser DevTools to inspect
+4. **Try setting explicit `minHeight`** to see if the feature is working:
+   ```tsx
+   <ReactIframe minHeight={200} ... />
+   ```
 
@@ -363,6 +495,24 @@ ### Styles not applying
 
-1. Inject styles programmatically into the iframe document
-2. Use CSS variables that can be passed through
-3. Include styles within your component
+1. **Use Tailwind CSS** - It's automatically available in the iframe
+2. **Inject styles programmatically** into the iframe document
+3. **Use CSS variables** that can be passed through for theming
+4. **Include styles within your component** using CSS-in-JS or style tags
 
+### Performance issues
+
+If you experience performance issues:
+
+1. **Disable auto-height** if not needed: `autoHeight={false}`
+2. **Use `minHeight` and `maxHeight`** to limit height calculations
+3. **Memoize component props** to prevent unnecessary re-renders
+4. **Check for memory leaks** - ensure components properly cleanup
+
+## 🔒 Security Considerations
+
+- Always use the `sandbox` attribute to restrict iframe capabilities
+- Be cautious with `allow-same-origin` - only use when necessary
+- Consider using `referrerPolicy` to control referrer information
+- Review the `allow` attribute to limit feature access
+- Test your security settings thoroughly
+
 ## 📝 License
@@ -382,11 +532,35 @@
 
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/idimetrix/react-iframe.git
+cd react-iframe
+
+# Install dependencies
+npm install
+
+# Run development server
+npm run dev
+
+# Build the library
+npm run build
+
+# Run type checking
+npm run typecheck
+```
+
 ## 📄 Changelog
 
 ### 1.0.0
-- Initial release
-- Full iframe prop propagation
-- Auto-height feature
-- TypeScript support
-- React 17/18/19 compatibility
 
+- ✨ Initial release
+- 🎯 Full iframe prop propagation
+- 📏 Auto-height feature (enabled by default)
+- 💪 TypeScript support
+- ⚡ React 17/18/19 compatibility
+- 🎨 Tailwind CSS integration
+- 🔧 Performance optimizations
+- 📚 Comprehensive documentation
+
 ---
@@ -398,2 +572,4 @@
 
+**[Report Bug](https://github.com/idimetrix/react-iframe/issues)** • **[Request Feature](https://github.com/idimetrix/react-iframe/issues)** • **[View on NPM](https://www.npmjs.com/package/@dimetrix/react-iframe)**
+
 </div>

New alerts

AI-detected possible typosquat

Supply chain risk

AI has identified this package as a potential typosquat of a more popular package. This suggests that the package may be intentionally mimicking another package's name, description, or other metadata.

Found 1 instance in 1 package

Network access

Supply chain risk

This module accesses the network.

Found 1 instance in 1 package

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Found 1 instance in 1 package

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Found 1 instance in 1 package

Fixed alerts

AI-detected possible typosquat

Supply chain risk

AI has identified this package as a potential typosquat of a more popular package. This suggests that the package may be intentionally mimicking another package's name, description, or other metadata.

Found 1 instance in 1 package

Network access

Supply chain risk

This module accesses the network.

Found 1 instance in 1 package

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Found 1 instance in 1 package

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

920143

0.62%

Number of lines in readme file

551

46.93%

No dependency changes