@extend-ai/react-pptx 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# @extend-ai/react-pptx
+
+## Unreleased
+
+- Expose consumer-owned slide thumbnail rails through `usePptxViewerThumbnails`, including stable
+  container refs, resolution bounds, render status, imperative rendering, and cleanup. Add
+  DOCX-style visible/prefetch render windows and virtualize the built-in thumbnail scrollport.
+
+## 0.1.0
+
+Initial public release of the React PowerPoint viewer, including:
+
+- Browser-native PPTX and legacy PPT parsing through Rust and WebAssembly.
+- A normalized presentation model and virtualized React viewer.
+- Embedded and host-provided font support with missing-font diagnostics.
+- Native legacy PowerPoint slide, drawing, text, and image fallback support.
+- Fidelity improvements for placeholders, backgrounds, text layout, gradients, and image fills.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Extend AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,203 @@
+# @extend-ai/react-pptx
+
+[![npm version](https://img.shields.io/npm/v/@extend-ai/react-pptx.svg)](https://www.npmjs.com/package/@extend-ai/react-pptx)
+
+Browser-native PowerPoint viewing for React.
+
+```bash
+npm install @extend-ai/react-pptx
+```
+
+React and React DOM are peer dependencies already present in a React application.
+
+## Main API
+
+- `ReactPptxViewer` renders URLs, `Blob`, `ArrayBuffer`, `Uint8Array`, parsed presentations, or normalized documents.
+- `parsePresentation` performs native parsing and returns the same normalized model the viewer renders.
+- `initWasm` and `setWasmSource` support eager initialization and custom Wasm/CDN hosting.
+- `PptxViewerController` provides navigation, zoom, fit, text search, highlighting, model access,
+  and detached thumbnail rendering.
+
+Import `@extend-ai/react-pptx/styles.css` alongside the component; the stylesheet is emitted as
+a separate package asset. Parsing and rendering are client-side; importing the JavaScript package
+during SSR is safe.
+
+Unknown or degraded content is surfaced through `onWarning` and `showDiagnostics` rather
+than silently removed.
+
+## Supported presentation formats
+
+`.pptx` and legacy PowerPoint 97–2003 `.ppt` files are both accepted by the same `source`
+prop and `parsePresentation()` API. Legacy files are opened natively from OLE compound
+storage by the Rust/Wasm parser; the browser does not need LibreOffice, a server-side
+conversion endpoint, or a temporary `.pptx` copy.
+
+For `.ppt`, the parser follows the `Current User`/`UserEditAtom` edit chain and live
+persist-object directory to recover the actual slide list. Supported OfficeArt group and
+shape anchors, text, pictures, and referenced master drawing content are normalized into
+the same `PresentationDocument` consumed by the React viewer. PNG/JPEG pictures render
+directly, while decoded EMF/WMF records use a bounded browser-side image conversion for
+static previews.
+
+Legacy rendering is static, not full PowerPoint emulation. Advanced effects, editable
+binary charts and tables, animations, transitions, active OLE objects, and timed media may
+degrade to a static picture or remain unsupported. Inspect `onWarning` or enable
+`showDiagnostics` to receive explicit `degraded-rendering` warnings:
+
+```tsx
+<ReactPptxViewer
+  source={file}
+  showDiagnostics
+  onWarning={(warning) => {
+    if (warning.code === 'degraded-rendering') {
+      console.warn(warning.message, warning.slideIndex);
+    }
+  }}
+/>
+```
+
+The repository regression suite opens a real three-slide PowerPoint 97–2003 file at
+`tests/fixtures/legacy/file-example-250kb.ppt` directly in Rust and the playground. It
+checks slide order, text, normalized nodes, thumbnail navigation, and diagnostics without
+a conversion step.
+
+## WebAssembly asset
+
+Native PowerPoint parsing runs through a WebAssembly module that loads lazily. Most apps can
+use the default loader. If your bundler or deployment needs to host the binary explicitly,
+configure it before the first presentation is parsed:
+
+```ts
+import { setWasmSource } from '@extend-ai/react-pptx';
+
+setWasmSource('https://cdn.example.com/pptx_wasm_bg.wasm');
+// A URL, Request, Response, ArrayBuffer/TypedArray, or WebAssembly.Module also works.
+```
+
+The binary is also available as a package subpath for bundlers that support asset URL imports:
+
+```ts
+import wasmUrl from '@extend-ai/react-pptx/pptx_wasm_bg.wasm?url';
+import { setWasmSource } from '@extend-ai/react-pptx';
+
+setWasmSource(wasmUrl);
+```
+
+Configured strings, URLs, request URLs, bytes, and `WebAssembly.Module` values are forwarded to
+the parser worker. A `Response` is supported on the main thread because it cannot be forwarded
+reliably to a worker. `initWasm()` optionally accepts the same source when eager initialization
+is useful.
+
+## Fonts
+
+Fonts embedded in a `.pptx` are decoded by the Rust parser and registered before the first
+slide is rendered. Applications can also provide licensed/self-hosted fonts. The viewer
+preserves the requested PowerPoint family, then appends Office-compatible and script-complete
+fallbacks for Latin, CJK, Arabic, Hebrew, emoji, and math glyphs.
+
+```tsx
+<ReactPptxViewer
+  source={file}
+  fonts={{
+    sources: [
+      { family: 'Brand Sans', source: '/fonts/brand-sans.woff2' },
+      {
+        family: 'Brand Sans',
+        source: '/fonts/brand-sans-bold.woff2',
+        descriptors: { weight: '700' },
+      },
+    ],
+    fallbacks: { 'Brand Sans': ['Inter', 'Arial'] },
+    fallbackFamilies: ['Noto Sans', 'Noto Sans CJK SC', 'Noto Sans Arabic'],
+  }}
+  onWarning={(warning) => {
+    if (warning.code === 'missing-font') console.warn(warning.message);
+  }}
+/>
+```
+
+The package does not redistribute proprietary Microsoft fonts. For identical metrics across
+machines, self-host the fonts your license permits or install metric-compatible families such
+as Carlito and Caladea. `resolvePptxFontFamily()` and `OFFICE_FONT_FALLBACKS` are exported for
+applications that also render presentation text outside the viewer.
+
+## Custom scroll areas and hooks
+
+Pass the actual scrolling viewport through `virtualization.scrollElement`. This works with
+Radix, Base UI, coss, or any host-owned scroll area and makes that element the observer root.
+
+```tsx
+const [scrollElement, setScrollElement] = useState<HTMLDivElement | null>(null);
+const viewer = usePptxViewer();
+const parsed = usePptxPresentation(file);
+
+return (
+  <ScrollArea.Root>
+    <ScrollArea.Viewport ref={setScrollElement}>
+      {parsed.presentation ? (
+        <ReactPptxViewer
+          ref={viewer.ref}
+          source={parsed.presentation}
+          virtualization={{ enabled: true, overscanViewport: 2, scrollElement }}
+        />
+      ) : null}
+    </ScrollArea.Viewport>
+  </ScrollArea.Root>
+);
+```
+
+`usePptxPresentation` (`usePptxModel` alias) separates parsing from rendering, while
+`usePptxViewer` exposes the reactive navigation/search/zoom controller. `onViewportReady`
+provides the internal slide surface for advanced integrations and test harnesses.
+
+## Thumbnail hook
+
+`usePptxViewerThumbnails` exposes detached slide previews for a consumer-owned filmstrip. PPTX
+thumbnails use the same live DOM/SVG renderer and loaded fonts as the main viewer, so attach each
+stable `containerRef` to a regular element rather than a canvas.
+
+```tsx
+import { ReactPptxViewer, usePptxViewer, usePptxViewerThumbnails } from '@extend-ai/react-pptx';
+
+export function PresentationWithThumbnails({ file }: { file: ArrayBuffer }) {
+  const viewer = usePptxViewer();
+  const { thumbnails } = usePptxViewerThumbnails(viewer.controller, {
+    resolution: { maxWidth: 180, maxHeight: 120 },
+    renderWindow: {
+      visibleSlideIndexes: [0, 1, 2],
+      prefetchSlideIndexes: [3, 4, 5],
+    },
+  });
+
+  return (
+    <div style={{ display: 'grid', gridTemplateColumns: '200px 1fr', gap: 16 }}>
+      <aside style={{ display: 'grid', gap: 12, alignContent: 'start' }}>
+        {thumbnails.map((thumbnail) => (
+          <button
+            key={thumbnail.slideIndex}
+            type="button"
+            onClick={() => void viewer.controller?.goToSlide(thumbnail.slideIndex)}
+          >
+            <div
+              ref={thumbnail.containerRef}
+              style={{
+                width: thumbnail.width,
+                height: thumbnail.height,
+                overflow: 'hidden',
+              }}
+            />
+          </button>
+        ))}
+      </aside>
+      <ReactPptxViewer ref={viewer.ref} source={file} mode="slide" />
+    </div>
+  );
+}
+```
+
+The result also provides `renderThumbnail(slideIndex, element)` for imperative integrations and
+`rerenderAttachedThumbnails()` for refreshing every currently attached preview. `disabled` keeps
+the metadata stable while pausing and disposing thumbnail rendering. For large decks, virtualize
+the rail against its actual scroll element: mount `containerRef` only for virtual rows, pass those
+rows through `renderWindow.visibleSlideIndexes`, and use `prefetchSlideIndexes` to warm nearby
+slides. The built-in `showThumbnails` filmstrip follows the same windowed behavior.

package/THIRD_PARTY_LICENSES/ISC.txt

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) the respective authors.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/THIRD_PARTY_LICENSES/MIT.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) the respective authors.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,29 @@
+# Third-party notices
+
+## Chart rendering stack (vendored from @extend-ai/react-xlsx)
+
+The chart renderer and chart model builder in `src/charts/` are vendored from
+[`@extend-ai/react-xlsx`](https://github.com/extend-hq/react-xlsx) (MIT) so
+PowerPoint charts render with the same styles and colors as Excel charts.
+
+The chart libraries `d3-scale`, `d3-shape`, `d3-hierarchy`, `d3-geo` (ISC,
+Copyright Mike Bostock), `topojson-client` (ISC), and
+[`regl`](https://github.com/regl-project/regl) (MIT) are declared as regular
+package dependencies.
+
+The published package bundles the
+[`us-atlas`](https://github.com/topojson/us-atlas) and
+[`world-atlas`](https://github.com/topojson/world-atlas) TopoJSON boundary data
+(ISC License) inside a dynamically imported chunk that only loads when a
+presentation contains an Excel map chart.
+
+The published package includes the ISC and MIT license texts at
+`THIRD_PARTY_LICENSES/ISC.txt` and `THIRD_PARTY_LICENSES/MIT.txt`.
+
+## Virtualized scrolling
+
+The continuous-scroll mode and React thumbnail rails are windowed with
+[`@tanstack/virtual-core`](https://github.com/TanStack/virtual) and
+[`@tanstack/react-virtual`](https://github.com/TanStack/virtual) (MIT License,
+Copyright (c) 2021-present Tanner Linsley), declared as regular package
+dependencies.

package/dist/chunk-YVOPQP3D.js

@@ -0,0 +1,50 @@
+// src/charts/region-map-data.ts
+function normalizeRegionMapKey(value) {
+  if (typeof value !== "string") {
+    return "";
+  }
+  return value.normalize("NFD").replace(/[\u0300-\u036f]/g, "").replace(/&/g, " and ").replace(/[^a-zA-Z0-9]+/g, " ").trim().toLowerCase().replace(/\s+/g, " ");
+}
+var REGION_MAP_COUNTRY_ALIASES = /* @__PURE__ */ new Map([
+  ["us", "united states of america"],
+  ["usa", "united states of america"],
+  ["u s a", "united states of america"],
+  ["united states", "united states of america"],
+  ["united states america", "united states of america"],
+  ["u s", "united states of america"],
+  ["uk", "united kingdom"],
+  ["u k", "united kingdom"],
+  ["uae", "united arab emirates"],
+  ["u a e", "united arab emirates"],
+  ["south korea", "korea, south"],
+  ["north korea", "korea, north"],
+  ["russia", "russian federation"],
+  ["vietnam", "viet nam"],
+  ["czech republic", "czechia"],
+  ["ivory coast", "cote d'ivoire"],
+  ["c\xF4te divoire", "cote d'ivoire"]
+]);
+var REGION_MAP_US_STATE_ALIASES = /* @__PURE__ */ new Map([
+  ["district of columbia", "district of columbia"],
+  ["washington dc", "district of columbia"],
+  ["washington d c", "district of columbia"],
+  ["dc", "district of columbia"],
+  ["d c", "district of columbia"]
+]);
+var loadedAtlas = null;
+var pendingAtlas = null;
+function getRegionMapAtlas() {
+  return loadedAtlas;
+}
+function loadRegionMapAtlas() {
+  if (loadedAtlas) return Promise.resolve(loadedAtlas);
+  pendingAtlas ??= import('./region-map-atlas-S2YXLDE2.js').then((module) => {
+    loadedAtlas = module.REGION_MAP_ATLAS;
+    return loadedAtlas;
+  });
+  return pendingAtlas;
+}
+
+export { REGION_MAP_COUNTRY_ALIASES, REGION_MAP_US_STATE_ALIASES, getRegionMapAtlas, loadRegionMapAtlas, normalizeRegionMapKey };
+//# sourceMappingURL=chunk-YVOPQP3D.js.map
+//# sourceMappingURL=chunk-YVOPQP3D.js.map

package/dist/chunk-YVOPQP3D.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/charts/region-map-data.ts"],"names":[],"mappings":";AAoBO,SAAS,sBAAsB,KAAA,EAAwB;AAC5D,EAAA,IAAI,OAAO,UAAU,QAAA,EAAU;AAC7B,IAAA,OAAO,EAAA;AAAA,EACT;AACA,EAAA,OAAO,KAAA,CACJ,UAAU,KAAK,CAAA,CACf,QAAQ,kBAAA,EAAoB,EAAE,CAAA,CAC9B,OAAA,CAAQ,IAAA,EAAM,OAAO,EACrB,OAAA,CAAQ,gBAAA,EAAkB,GAAG,CAAA,CAC7B,IAAA,GACA,WAAA,EAAY,CACZ,OAAA,CAAQ,MAAA,EAAQ,GAAG,CAAA;AACxB;AAEO,IAAM,0BAAA,uBAAiC,GAAA,CAAoB;AAAA,EAChE,CAAC,MAAM,0BAA0B,CAAA;AAAA,EACjC,CAAC,OAAO,0BAA0B,CAAA;AAAA,EAClC,CAAC,SAAS,0BAA0B,CAAA;AAAA,EACpC,CAAC,iBAAiB,0BAA0B,CAAA;AAAA,EAC5C,CAAC,yBAAyB,0BAA0B,CAAA;AAAA,EACpD,CAAC,OAAO,0BAA0B,CAAA;AAAA,EAClC,CAAC,MAAM,gBAAgB,CAAA;AAAA,EACvB,CAAC,OAAO,gBAAgB,CAAA;AAAA,EACxB,CAAC,OAAO,sBAAsB,CAAA;AAAA,EAC9B,CAAC,SAAS,sBAAsB,CAAA;AAAA,EAChC,CAAC,eAAe,cAAc,CAAA;AAAA,EAC9B,CAAC,eAAe,cAAc,CAAA;AAAA,EAC9B,CAAC,UAAU,oBAAoB,CAAA;AAAA,EAC/B,CAAC,WAAW,UAAU,CAAA;AAAA,EACtB,CAAC,kBAAkB,SAAS,CAAA;AAAA,EAC5B,CAAC,eAAe,eAAe,CAAA;AAAA,EAC/B,CAAC,mBAAgB,eAAe;AAClC,CAAC;AAEM,IAAM,2BAAA,uBAAkC,GAAA,CAAoB;AAAA,EACjE,CAAC,wBAAwB,sBAAsB,CAAA;AAAA,EAC/C,CAAC,iBAAiB,sBAAsB,CAAA;AAAA,EACxC,CAAC,kBAAkB,sBAAsB,CAAA;AAAA,EACzC,CAAC,MAAM,sBAAsB,CAAA;AAAA,EAC7B,CAAC,OAAO,sBAAsB;AAChC,CAAC;AAED,IAAI,WAAA,GAAqC,IAAA;AACzC,IAAI,YAAA,GAA+C,IAAA;AAG5C,SAAS,iBAAA,GAA2C;AACzD,EAAA,OAAO,WAAA;AACT;AAGO,SAAS,kBAAA,GAA8C;AAC5D,EAAA,IAAI,WAAA,EAAa,OAAO,OAAA,CAAQ,OAAA,CAAQ,WAAW,CAAA;AACnD,EAAA,YAAA,KAAiB,OAAO,gCAAoB,CAAA,CAAE,IAAA,CAAK,CAAC,MAAA,KAAW;AAC7D,IAAA,WAAA,GAAc,MAAA,CAAO,gBAAA;AACrB,IAAA,OAAO,WAAA;AAAA,EACT,CAAC,CAAA;AACD,EAAA,OAAO,YAAA;AACT","file":"chunk-YVOPQP3D.js","sourcesContent":["/**\n * Region-map registry shared by the chart renderer and the lazily loaded\n * atlas chunk. The multi-megabyte TopoJSON boundary data only loads when a\n * presentation actually contains an Excel map chart; until then the renderer\n * sees an empty registry and draws the map without shapes.\n */\nimport type { Feature, Geometry } from 'geojson';\n\nexport type RegionMapFeature = Feature<\n  Geometry,\n  { name?: string; regionSet?: 'country' | 'us-state'; stateCode?: string }\n>;\n\nexport interface RegionMapAtlas {\n  worldCountryFeatures: RegionMapFeature[];\n  usStateFeatures: RegionMapFeature[];\n  countryFeaturesByKey: Map<string, RegionMapFeature>;\n  usStateFeaturesByKey: Map<string, RegionMapFeature>;\n}\n\nexport function normalizeRegionMapKey(value: unknown): string {\n  if (typeof value !== 'string') {\n    return '';\n  }\n  return value\n    .normalize('NFD')\n    .replace(/[\\u0300-\\u036f]/g, '')\n    .replace(/&/g, ' and ')\n    .replace(/[^a-zA-Z0-9]+/g, ' ')\n    .trim()\n    .toLowerCase()\n    .replace(/\\s+/g, ' ');\n}\n\nexport const REGION_MAP_COUNTRY_ALIASES = new Map<string, string>([\n  ['us', 'united states of america'],\n  ['usa', 'united states of america'],\n  ['u s a', 'united states of america'],\n  ['united states', 'united states of america'],\n  ['united states america', 'united states of america'],\n  ['u s', 'united states of america'],\n  ['uk', 'united kingdom'],\n  ['u k', 'united kingdom'],\n  ['uae', 'united arab emirates'],\n  ['u a e', 'united arab emirates'],\n  ['south korea', 'korea, south'],\n  ['north korea', 'korea, north'],\n  ['russia', 'russian federation'],\n  ['vietnam', 'viet nam'],\n  ['czech republic', 'czechia'],\n  ['ivory coast', \"cote d'ivoire\"],\n  ['côte divoire', \"cote d'ivoire\"],\n]);\n\nexport const REGION_MAP_US_STATE_ALIASES = new Map<string, string>([\n  ['district of columbia', 'district of columbia'],\n  ['washington dc', 'district of columbia'],\n  ['washington d c', 'district of columbia'],\n  ['dc', 'district of columbia'],\n  ['d c', 'district of columbia'],\n]);\n\nlet loadedAtlas: RegionMapAtlas | null = null;\nlet pendingAtlas: Promise<RegionMapAtlas> | null = null;\n\n/** Synchronous accessor used by the renderer; null until the chunk loads. */\nexport function getRegionMapAtlas(): RegionMapAtlas | null {\n  return loadedAtlas;\n}\n\n/** Loads the atlas chunk on demand; resolves immediately once cached. */\nexport function loadRegionMapAtlas(): Promise<RegionMapAtlas> {\n  if (loadedAtlas) return Promise.resolve(loadedAtlas);\n  pendingAtlas ??= import('./region-map-atlas').then((module) => {\n    loadedAtlas = module.REGION_MAP_ATLAS;\n    return loadedAtlas;\n  });\n  return pendingAtlas;\n}\n"]}