feat(superdoc): support fixed-height container embedding with contained mode (SD-2242) (#2423)

* feat(superdoc): support fixed-height container embedding with contained mode

SD-2242: Add `contained` option that enables SuperDoc to scroll within a
fixed-height parent container. When `contained: true`, height propagates
through the DOM chain and `.super-editor-container` becomes the scroll
container with `overflow: auto`.

Key changes:
- New `contained` boolean in Config type and React props
- CSS height chain: .superdoc--contained → layers → document → sub-document
- .super-editor-container.contained becomes scroll container (overflow: auto)
- .super-editor overflow changed from hidden to visible in contained mode
- CommentsLayer switched to position: absolute with pointer-events: none
  in contained mode to avoid blocking scroll and taking flow space
- React wrapper conditionally sets height: 100% on editor container

* docs: add contained mode configuration to SuperDoc and React docs

Document the new `contained` option in both the vanilla SuperDoc
configuration page and the React component configuration page,
with usage examples showing fixed-height container embedding.

* fix(react): use flex layout for contained mode to account for toolbar

When contained mode is active with a visible toolbar, height: 100%
on the editor container would overflow. Switch to flex layout so
toolbar and editor share the fixed-height wrapper properly.

* feat(superdoc): add contained mode scroll support for PDF and HTML viewers

The sub-document container gets overflow: auto in contained mode so
PDF and HTML documents scroll within fixed-height containers, not
just DOCX. SuperEditor already manages its own scroll container.

* fix(react): resolve type-check error for contained prop access

The contained property is defined via JSDoc in superdoc's types and
may not appear in generated .d.ts files. Use a type assertion instead
of accessing restProps.contained directly.

* chore: add pre-commit type-check hook for React package

* fix(superdoc): restore pointer-events on comment anchors in contained mode

The comments layer has pointer-events: none in contained mode to let
scroll events pass through, but this also disables comment highlight
clicks. Re-enable pointer-events on .sd-comment-anchor so comments
remain interactive.

* docs: update AGENTS.md and docs snippet to use contained mode

Add contained mode section to AGENTS.md for AI agent consumers.
Simplify the docs embed component by replacing manual CSS height/
overflow hacks with contained: true.

* docs: add contained mode section to CLAUDE.md

* docs(create): add contained option to AGENTS.md config table

* docs(react): add contained mode section to AGENTS.md and CLAUDE.md

* refactor(react): make contained an explicit React prop

Instead of accessing contained through restProps with an unsafe cast,
add it to ReactProps interface and destructure it like hideToolbar.
This gives TypeScript users autocomplete and removes the cast.

* fix(react): resolve type-check error from empty @types/minimatch

The root node_modules/@types/minimatch is an empty shell with no .d.ts
files. TypeScript auto-discovers all @types/* packages and fails on it.
Set explicit types in tsconfig to only include react and react-dom.

* fix(react): address review findings for contained prop

- Pass contained unconditionally (always boolean, no need for spread)
- Add contained to useEffect dep array so toggling triggers rebuild

Author: caio-pizzol

apps/create/src/templates.ts

@@ -172,6 +172,7 @@ Key options for the editor:
 | \`documentMode\` | \`'editing' \\| 'viewing' \\| 'suggesting'\` | Editor mode |
 | \`user\` | \`{ name, email }\` | Current user (for comments/tracked changes) |
 | \`toolbar\` | \`string \\| HTMLElement\` | Toolbar mount selector or element |
+| \`contained\` | \`boolean\` | Scroll inside a fixed-height parent instead of expanding |
 | \`modules.comments\` | \`object\` | Comments panel configuration |
 | \`modules.collaboration\` | \`object\` | Real-time collaboration (Yjs) |
 

apps/docs/core/react/configuration.mdx

@@ -78,6 +78,23 @@ All props are passed directly to the `<SuperDocEditor>` component. Only `documen
   Hide the toolbar.
 </ParamField>
 
+<ParamField path="contained" type="boolean" default="false">
+  Enable contained mode for fixed-height container embedding. When `true`, SuperDoc fits within its parent's height and scrolls internally.
+
+  Your wrapper must have a definite height (e.g., `height: 400px`, `flex: 1`, or a CSS class with a fixed height). Pass `style={{ height: '100%' }}` to propagate the height.
+
+  ```jsx
+  <div style={{ height: 500 }}>
+    <SuperDocEditor
+      document={file}
+      documentMode="viewing"
+      contained
+      style={{ height: '100%' }}
+    />
+  </div>
+  ```
+</ParamField>
+
 <ParamField path="rulers" type="boolean">
   Show or hide rulers. Uses SuperDoc default if not set.
 </ParamField>

apps/docs/core/superdoc/configuration.mdx

@@ -395,6 +395,42 @@ new SuperDoc({
   ```
 </ParamField>
 
+<ParamField path="contained" type="boolean" default="false">
+  Enable contained mode for fixed-height container embedding. When `true`, SuperDoc fits within its parent's height and scrolls internally instead of expanding to the document's natural height. Works with DOCX, PDF, and HTML documents.
+
+  Use this when embedding SuperDoc inside a panel, sidebar, or any container with a fixed height (e.g., `height: 400px` or `flex: 1`).
+
+  <CodeGroup>
+
+  ```javascript Usage
+  const superdoc = new SuperDoc({
+    selector: '#editor',
+    document: file,
+    contained: true,
+  });
+  ```
+
+  ```html Full Example
+  <!-- Parent must have a definite height -->
+  <div style="height: 500px;">
+    <div id="editor"></div>
+  </div>
+
+  <script type="module">
+    import { SuperDoc } from 'superdoc';
+    import 'superdoc/style.css';
+
+    new SuperDoc({
+      selector: '#editor',
+      document: yourFile,
+      contained: true,
+    });
+  </script>
+  ```
+
+  </CodeGroup>
+</ParamField>
+
 <ParamField path="layoutMode" type="string" deprecated>
   <Warning>**Removed in v1.0** — Use `viewOptions.layout` instead. `'paginated'` → `'print'`, `'responsive'` → `'web'`.</Warning>
 </ParamField>

apps/docs/snippets/components/superdoc-editor.jsx

@@ -79,6 +79,7 @@ export const SuperDocEditor = ({
         selector: `#${containerIdRef.current}`,
         html,
         rulers: true,
+        contained: true,
         onReady: () => {
           setReady(true);
           if (onReady) onReady(editorRef.current);
@@ -151,26 +152,17 @@ export const SuperDocEditor = ({
           )}
         </div>
       )}
-      <div
-        id={containerIdRef.current}
-        style={{ minHeight: height, maxHeight, paddingLeft: '5px', overflow: 'scroll' }}
-      />
+      <div id={containerIdRef.current} style={{ height, maxHeight, paddingLeft: '5px' }} />
       <style jsx>{`
         #${containerIdRef.current} .superdoc__layers {
           max-width: 660px !important;
         }
-        #${containerIdRef.current} .super-editor-container {
-          min-width: unset !important;
-          min-height: unset !important;
-          width: 100% !important;
-        }
         #${containerIdRef.current} .super-editor {
           max-width: 100% !important;
           width: 100% !important;
           color: #000;
         }
         #${containerIdRef.current} .editor-element {
-          min-height: ${height} !important;
           width: 100% !important;
           min-width: unset !important;
           transform: none !important;

lefthook.yml

@@ -24,6 +24,10 @@ pre-commit:
       root: "apps/docs/"
       glob: "apps/docs/**/*.mdx"
       run: pnpm run test:examples
+    react-type-check:
+      root: "packages/react/"
+      glob: "packages/react/**/*.{ts,tsx}"
+      run: pnpm run type-check
     generate-all:
       glob: "packages/document-api/src/contract/**/*.ts"
       run: pnpm run generate:all && git add apps/docs/document-api/reference apps/docs/document-api/overview.mdx apps/docs/document-engine/sdks.mdx

packages/react/AGENTS.md

@@ -45,6 +45,21 @@ export interface SuperDocEditorProps
 | `className` | `string` | - | Wrapper CSS class |
 | `style` | `CSSProperties` | - | Wrapper inline styles |
 
+## Fixed-height container embedding
+
+Pass `contained` to scroll inside a fixed-height parent. The wrapper must have a definite height.
+
+```tsx
+<div style={{ height: 500 }}>
+  <SuperDocEditor
+    document={file}
+    documentMode="viewing"
+    contained
+    style={{ height: '100%' }}
+  />
+</div>
+```
+
 ## SSR Behavior
 
 - Container divs are always rendered (hidden with `display: none` until initialized)

packages/react/src/SuperDocEditor.tsx

@@ -38,6 +38,7 @@ function SuperDocEditorInner(props: SuperDocEditorProps, ref: ForwardedRef<Super
     id,
     renderLoading,
     hideToolbar = false,
+    contained = false,
     className,
     style,
     // Callbacks (stored in ref to avoid triggering rebuilds)
@@ -149,6 +150,7 @@ function SuperDocEditorInner(props: SuperDocEditorProps, ref: ForwardedRef<Super
           ...(!hideToolbar && toolbarContainerRef.current ? { toolbar: `#${CSS.escape(toolbarId)}` } : {}),
           documentMode,
           role,
+          contained,
           ...(documentProp != null ? { document: documentProp } : {}),
           ...(user ? { user } : {}),
           ...(users ? { users } : {}),
@@ -224,17 +226,26 @@ function SuperDocEditorInner(props: SuperDocEditorProps, ref: ForwardedRef<Super
     // initial values - use getInstance() methods to change them at runtime.
     // Note: restProps is intentionally excluded to avoid rebuilds on every render.
     // documentMode is handled separately via setDocumentMode() for efficiency.
-  }, [documentProp, user, users, modules, role, hideToolbar, containerId, toolbarId]);
+  }, [documentProp, user, users, modules, role, hideToolbar, contained, containerId, toolbarId]);
 
   const wrapperClassName = ['superdoc-wrapper', className].filter(Boolean).join(' ');
   const hideWhenLoading: CSSProperties | undefined = isLoading ? { display: 'none' } : undefined;
 
+  const wrapperStyle: CSSProperties = {
+    ...style,
+    ...(contained && { display: 'flex', flexDirection: 'column' as const }),
+  };
+
   return (
-    <div className={wrapperClassName} style={style}>
+    <div className={wrapperClassName} style={wrapperStyle}>
       {!hideToolbar && (
         <div ref={toolbarContainerRef} id={toolbarId} className='superdoc-toolbar-container' style={hideWhenLoading} />
       )}
-      <div id={containerId} className='superdoc-editor-container' style={hideWhenLoading} />
+      <div
+        id={containerId}
+        className='superdoc-editor-container'
+        style={{ ...hideWhenLoading, ...(contained && { flex: 1, minHeight: 0 }) }}
+      />
       {isLoading && !hasError && renderLoading && <div className='superdoc-loading-container'>{renderLoading()}</div>}
       {hasError && <div className='superdoc-error-container'>Failed to load editor. Check console for details.</div>}
     </div>

packages/react/src/types.ts

@@ -136,6 +136,10 @@ interface ReactProps {
   /** Hide the toolbar container. When true, no toolbar is rendered. @default false */
   hideToolbar?: boolean;
 
+  /** Enable contained mode for fixed-height container embedding. When true, SuperDoc
+   *  fits within its parent's height and scrolls internally. @default false */
+  contained?: boolean;
+
   /** Additional CSS class name for the wrapper element */
   className?: string;
 

packages/react/tsconfig.json

@@ -6,7 +6,8 @@
     "rootDir": "./src",
     "jsx": "react-jsx",
     "forceConsistentCasingInFileNames": true,
-    "allowSyntheticDefaultImports": true
+    "allowSyntheticDefaultImports": true,
+    "types": ["react", "react-dom"]
   },
   "include": ["src/**/*"],
   "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.test.tsx"]

packages/super-editor/src/editors/v1/components/SuperEditor.vue

@@ -72,6 +72,10 @@ const isWebLayout = computed(() => {
   return props.options.viewOptions?.layout === 'web';
 });
 
+const isContained = computed(() => {
+  return Boolean(props.options.contained);
+});
+
 /**
  * Reactive ruler visibility state.
  * Uses a ref with a deep watcher to ensure proper reactivity when options.rulers changes.
@@ -1264,7 +1268,11 @@ onBeforeUnmount(() => {
 </script>
 
 <template>
-  <div class="super-editor-container" :class="{ 'web-layout': isWebLayout }" :style="containerStyle">
+  <div
+    class="super-editor-container"
+    :class="{ 'web-layout': isWebLayout, contained: isContained }"
+    :style="containerStyle"
+  >
     <!-- Ruler: teleport to external container if specified, otherwise render inline (hidden in web layout) -->
     <Teleport
       v-if="options.rulerContainer && rulersVisible && !isWebLayout && !!activeEditor"
@@ -1403,4 +1411,20 @@ onBeforeUnmount(() => {
   overflow: hidden;
   position: relative;
 }
+
+/* Contained mode: fixed-height container embedding with internal scrolling.
+ * The super-editor-container becomes the scroll container (overflow: auto).
+ * The .super-editor overflow is changed from hidden to visible so content
+ * flows through to the scroll container. The visibleHost (.presentation-editor)
+ * stays overflow: visible per PresentationEditor's design — it is NOT the scroller.
+ */
+.super-editor-container.contained {
+  height: 100%;
+  min-height: 0;
+  overflow: auto;
+}
+
+.super-editor-container.contained .super-editor {
+  overflow: visible;
+}
 </style>