SD-3294 - add layout-change event for responsive fit-to-container zoom

[mattConnHarbour]

Summary

• Adds layout-change event that fires when the container width changes
• Captures document width once at initial load (before any zoom) to prevent feedback loops when setZoom() changes the DOM dimensions
• Provides fitZoom - the calculated zoom percentage to fit document in container
• Users must call setZoom() and apply their own min/max clamping

Payload

  interface SuperDocLayoutChangePayload {
    containerWidth: number;  // Container width in px
    documentWidth: number;   // Base document width (captured at 100% zoom)
    fitZoom: number;         // Calculated zoom to fit - (containerWidth / documentWidth) * 100
  }

Usage

  superdoc.on('layout-change', ({ fitZoom }) => {
    if (fitZoom < MIN_ZOOM) {
      superdoc.setZoom(MIN_ZOOM);
    } else if (fitZoom > MAX_ZOOM) {
      superdoc.setZoom(MAX_ZOOM);
    } else {
      superdoc.setZoom(fitZoom);
    }
  });

[linear-code]

SD-3294

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 31fd208bf8

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[cubic-dev-ai]

cubic analysis

2 issues found across 4 files

Linked issue analysis

Linked issue: SD-3294: Add layout-change event for responsive fit-to-container zoom

Status	Acceptance criteria	Notes
✅	Emit a 'layout-change' event when the container width changes	The PR registers a watcher on the container width and calls emitLayoutChange, which emits the event when fitZoom changes.
✅	Payload includes containerWidth, documentWidth (base captured at 100% zoom), and fitZoom	The emitted payload contains containerWidth, documentWidth (baseDocumentWidth), and fitZoom; the types file adds SuperDocLayoutChangePayload with those fields.
✅	Capture document width once at initial load (before any zoom) to avoid feedback loops	baseDocumentWidth is initialized null and set only on the first emitLayoutChange call by measuring the document element, so the base width is captured once.
✅	Prevent feedback loops by rounding fitZoom and emitting only when it actually changes	fitZoom is computed via Math.round and compared against lastEmittedFitZoom; the event is returned early if unchanged.
✅	Register the new event in the SuperDoc event map/types so consumers can type-check handlers	The event map in SuperDoc.ts includes 'layout-change' and the payload type is added to the core types file.

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[caio-pizzol]

Hey Matt, quick heads up on SD-3294. I stacked #3659 on top of this PR, and it changes the unreleased API a bit, so I wanted to flag it before I merge it into your branch.

Main changes:

• Renamed layout-change to viewport-change because layout-change is already used elsewhere and could be confusing.
• Changed the width calculation so zoom no longer affects it. It now re-checks page width each time, including wide pages and PDFs.
• Added zoom modes: manual and fit-width. setZoom() switches to manual, and setZoomMode('fit-width') turns fitting back on. It also adds config, state helpers, Custom UI support, and a toolbar command.

Your event idea and payload shape are still there. The naming and internals changed to make the feature safer before it ships.

#3659 has been reviewed, follow-ups are fixed or ticketed in SD-3390, and CI SuperDoc is green on the current head. One note: stacked PRs do not run that suite automatically, so I dispatched it manually.

There is also a small example PR, #3667, stacked on top. That one can wait.

[github-actions]

📖 Docs preview: https://superdoc-matthew-sd-3294-layout-change-event.mintlify.app