* docs: define renderer editor task 1 integration * docs: plan renderer editor task 1 * feat: gate renderer slide editor * feat: adapt renderer editor intents * feat: connect renderer editor to slide surface * test: complete renderer intent shape fixture * fix: restore renderer editor action previews * fix: render editor alignment guides * perf: smooth renderer element dragging * feat: align renderer hidden element behavior * feat: add renderer canvas host commands * feat: add renderer canvas context interactions * test: cover renderer context menu interaction * fix: preserve renderer canvas interaction semantics * docs: design renderer text editing * docs: plan renderer text editing * feat(renderer): add ProseMirror text core * feat(renderer): add rich text editor controller * feat(renderer): render editable text in place * feat(renderer): enter text editing on click * feat: connect renderer rich text editing * feat: finalize renderer text edit lifecycle * fix: stabilize renderer text edit commits * fix(renderer): move elements from selected borders * docs: design renderer editing UI text toolbar * feat(renderer): publish editing UI contracts * feat(renderer): add controlled text format toolbar * style(renderer): format editing UI contracts * fix(renderer): address Task 2 review findings * fix(renderer): handle zero font sizes in toolbar * feat(renderer): add editing UI color picker * fix(renderer): address Task 3 color picker review * fix(renderer): commit native color input changes * fix(renderer): coordinate native color picker interaction * feat(renderer): anchor text toolbar to canvas elements * feat(renderer): compose editable canvas with text UI * feat(editor): use renderer text toolbar UI * fix(renderer): make editing UI tests type-safe * fix(renderer): harden editing UI integration * feat(renderer): add editable text UI * feat(renderer): add image and shape editing * feat(editor): extend renderer editing controls * feat(editor): add renderer chart insertion * docs: design renderer latex editor * docs: plan renderer latex editor * feat(renderer): add latex editor contract * feat(renderer): add latex editor dialog * feat(renderer): compose latex insert and edit UI * feat(editor): integrate renderer latex editing * fix(editor): consolidate latex toolbar actions * fix(renderer): show toolbar hover labels * test(renderer): cover localized latex tooltips * chore(renderer): hide latex sample palette * feat(renderer): add video editing controls * docs: define renderer audio editing * feat(renderer): render audio elements * feat(renderer): add audio editing UI * feat(renderer): add preview audio controls * feat(editor): add renderer element clipboard * feat(renderer): decouple editor UI from app * chore(renderer): release 0.0.6 * fix(renderer): clear editor CI gates * fix(editor): adapt renderer canvas to media resolution API * fix(i18n): complete French editor labels * fix(renderer): hide toolbar vertical overflow * chore(renderer): address review cleanup * chore(docs): remove planning artifacts from pr * feat(editor): add transactional core package * chore(editor): ignore local test cache * build(editor): publish core entrypoint * refactor(editor): route renderer changes through transactions * refactor(editor): split renderer editing into editor package * ci(editor): register editor package for release * docs(editor): document package dependencies * ci: rerun validation after editor release registration * test(editor): validate deletion against existing element * fix(editor): address transaction and package review findings * fix(editor): validate transactions and restore editor styles * fix(editor): protect required updates and react styles * fix(editor): validate required transaction fields * fix(editor): prevent insert popovers shifting canvas * refactor(editor): own renderer editing capabilities * fix(editor): harden editing transaction boundaries * refactor(editor): modularize editor UI integration * docs(editor): harden third-party integration * fix(editor): preserve video resize aspect ratio * fix(editor): discard text draft before deletion * fix(editor): preserve renderer picking and line presets * chore(editor): remove unused pick-layer import
7.1 KiB
@openmaic/renderer
React component for rendering PPTist-style Slide JSON. Extracted from OpenMAIC.
@openmaic/rendereris the read-only canvas package. Editing lives in the separate@openmaic/editorpackage, which depends on this renderer.
Migrating from 0.0.x
Version 0.1.0 removes the experimental @openmaic/renderer/editing subpath.
Install @openmaic/editor and migrate editing imports to its explicit layers:
import { EditableSlideCanvas } from '@openmaic/editor/react';
import { EditableSlideCanvasWithUI } from '@openmaic/editor/ui';
Read-only rendering imports from @openmaic/renderer are unchanged.
Install
pnpm add @openmaic/renderer
# or
npm install @openmaic/renderer
Required peers:
react >= 18react-dom >= 18motion >= 11tailwindcss >= 4— the package emits Tailwind 4 arbitrary-value classes, consumers must use Tailwind 4
Optional peers (install only if your slides use the corresponding element type):
echarts >= 5— for chart elementsshiki >= 1— for code elements
Quickstart
import { SlideCanvas, type Slide } from '@openmaic/renderer';
const slide: Slide = {
id: 'demo-1',
viewportSize: 1000,
viewportRatio: 0.5625,
theme: {
backgroundColor: '#ffffff',
themeColors: ['#5b8def'],
fontColor: '#222222',
fontName: 'sans-serif',
},
elements: [
{
type: 'text',
id: 't1',
left: 100,
top: 80,
width: 800,
height: 60,
rotate: 0,
content: '<p>Hello, Slide</p>',
defaultFontName: 'sans-serif',
defaultColor: '#222',
},
],
background: { type: 'solid', color: '#ffffff' },
};
export default function Demo() {
return (
<div style={{ width: 800, height: 450 }}>
<SlideCanvas slide={slide} />
</div>
);
}
The canvas auto-fits its parent container. The parent must have a defined width × height.
API
<SlideCanvas slide effects? renderImage? renderVideo? onElementClick? scale? background? />
The main read-only entry. Reads everything from props; zero global state.
interface SlideCanvasProps {
slide?: Slide; // required unless via <SlideRendererProvider>
scale?: number; // omit = auto-fit container
canvasPercentage?: number; // percent of the parent used by auto-fit
onScaleChange?: (scale) => void; // computed auto-fit scale
background?: SlideBackground; // overrides slide.background
effects?: SlideEffects; // laser / spotlight / highlight / zoom, all default off
renderImage?: (el, src, defaultContent) => ReactNode;
renderVideo?: (el) => ReactNode;
videoInteractive?: boolean; // defaults true; set false to disable video pointer interaction
onElementClick?: (el, event) => void;
elementIdPrefix?: string;
className?: string;
style?: CSSProperties;
}
Play-time effects
All effects are off by default. Pass any combination via effects:
<SlideCanvas
slide={slide}
effects={{
laser: { elementId: 't1', color: '#ff3b30' },
spotlight: { elementId: 't1' },
highlight: { elementId: 't1', color: '#ff6b6b', animated: true },
zoom: { elementId: 't1', scale: 1.5 },
}}
/>
Media injection slots
The package's BaseImageElement and BaseVideoElement render plain <img> / <video> and know nothing about your media pipeline. Inject business behaviour via the renderImage / renderVideo slots:
<SlideCanvas
slide={slide}
renderImage={(el, src, defaultContent) => (
src.startsWith('placeholder:')
? <MyPlaceholder taskId={src} />
: defaultContent
)}
/>
defaultContent is the renderer-prepared image, including clipping, filters,
soft edges, and colorMask. The slot return value is authoritative: return
null to intentionally hide the image.
<SlideRendererProvider> + useSlideContext()
Optional high-order pattern when sibling overlays need the same slide data:
import { SlideRendererProvider, SlideCanvas, useSlideContext } from '@openmaic/renderer';
function MyAnnotationLayer() {
const { slide } = useSlideContext();
return <div>Annotations for {slide.id}</div>;
}
<SlideRendererProvider slide={slide} scale={0.9}>
<SlideCanvas /> {/* reads slide/scale from context */}
<MyAnnotationLayer />
</SlideRendererProvider>
Granular components — @openmaic/renderer/elements
If you want to compose your own layout instead of using SlideCanvas, the 9 base elements are exported individually:
import {
BaseTextElement, BaseShapeElement, BaseImageElement,
BaseLineElement, BaseChartElement, BaseLatexElement,
BaseTableElement, BaseVideoElement, BaseCodeElement,
ElementOutline,
} from '@openmaic/renderer/elements';
Each accepts { elementInfo: PPTXxxElement }. Image/Video also take a render slot.
Types — @openmaic/renderer/types
import type {
Slide, PPTElement, SlideBackground, SlideTheme,
PPTTextElement, PPTShapeElement, PPTImageElement,
PPTLineElement, PPTChartElement, PPTLatexElement,
PPTTableElement, PPTVideoElement, PPTCodeElement,
ImageElementClip, ImageElementFilters,
Gradient, GradientType, PPTElementOutline, PPTElementShadow,
SlideEffects, LaserEffectOptions, SpotlightEffectOptions,
HighlightEffectOptions, ZoomEffectOptions,
} from '@openmaic/renderer/types';
Tailwind 4 setup
Ensure your tailwind.config.{ts,js} includes the package source:
export default {
content: [
'./src/**/*.{ts,tsx}',
'./node_modules/@openmaic/renderer/dist/**/*.{js,cjs}',
],
};
Fonts (optional, CDN-hosted)
Slides imported from PowerPoint often reference Chinese faces that aren't
installed on the viewer's machine. The package ships a fonts.css with
@font-face rules for a small whitelist of self-hosted CJK faces — import it
once at your app shell to make those faces available:
import '@openmaic/renderer/fonts.css';
Runtime dependency — read this. The
@font-facesrcURLs point at an external font host (https://file.maic.chat/fonts/<name>.woff2); the woff2 files are not bundled in the package. So this is a hard runtime dependency: the host must be reachable and CORS-enabled from the consumer's app, or the browser will silently fall back to system fonts (no error, just different glyphs/metrics). If you need a different origin (self-hosting, air-gapped, a private CDN), changeFONT_CDN_BASE_URLinfonts.config.mjsand regenerate withpnpm run genfonts.The import is optional — slides render fine without it, using whatever fonts the system provides. See FONTS.md for the face list and their licenses.
Companion package
@openmaic/importer converts .pptx files to the same Slide[] shape, so you can do .pptx → @openmaic/renderer end-to-end.
See also
- DESIGN.md — package design decisions and scope
- v2 will add editing (
<SlideEditor editable onChange />); the read-only<SlideCanvas>API will remain stable
License
MIT