Migrating to v1.0

What changed in @docmosaic/core 1.0 and @docmosaic/react 1.0, and how to update consumer code.

@docmosaic/core and @docmosaic/react graduated from 0.1.x to 1.0.0. The upgrade removes deprecated aliases that accumulated across the 0.x preview phases. Everything was marked @deprecated (or carried an explicit deprecation note) for at least one minor before removal, so most consumers should already be migrated.

TL;DR

Six Editor.* namespace aliases are gone - switch to the canonical names.
The bundled minimal-dark.css theme is gone - import styles.css and toggle .dark instead.
No type or runtime behavior changes outside the deletions. The PDF generation pipeline, document model, reducer, history, and primitives all behave the same.

Renamed primitives

The compound Editor.* namespace dropped the legacy alias names. Each was a re-export of the canonical primitive, so the migration is a pure rename.

Removed alias	Use instead	Notes
`Editor.Inspector`	`Editor.Properties`	Renamed for clarity
`Editor.PageBackgroundPicker`	`Editor.PageBackground`	Renamed for symmetry with other primitives
`Editor.EstimatedSize`	`Editor.FileSizeBadge`	More descriptive - it renders a badge
`Editor.ProgressOverlay`	`Editor.GenerationProgress`	More specific - it's PDF-generation progress
`Editor.AddSectionButton`	`Editor.AddImageButton`	Disambiguated from text/shape/draw add-buttons
`Editor.PageList`	`Editor.Pages`	Shorter, more idiomatic
`Editor.PageThumb`	`Editor.PageThumbnail`	Full word for readability

Removed `minimal-dark.css` theme

@docmosaic/react/styles/themes/minimal-dark.css is gone. The DocMosaic brand theme ships its own .dark scope (since 0.2), so a separate dark stylesheet is no longer needed.

- import '@docmosaic/react/styles/base.css';
- import '@docmosaic/react/styles/themes/minimal-dark.css';
+ import '@docmosaic/react/styles.css';

Then toggle the .dark class on <html> (typically via next-themes):

// app/layout.tsx
import { ThemeProvider } from 'next-themes';
import '@docmosaic/react/styles.css';

export default function Layout({ children }: { children: React.ReactNode }) {
    return (
        <html lang="en" suppressHydrationWarning>
            <body>
                <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
                    {children}
                </ThemeProvider>
            </body>
        </html>
    );
}

See the dark mode recipe for the full setup.

Codemods

The deprecated aliases ran for several minors with @deprecated JSDoc warnings, so most editors and bundlers will already have surfaced these. For projects that didn't migrate yet:

Rename `Editor.*` aliases in TSX

git ls-files '*.ts' '*.tsx' '*.mdx' \
  | xargs sed -i '' \
    -e 's/Editor\.Inspector\b/Editor.Properties/g' \
    -e 's/Editor\.PageBackgroundPicker\b/Editor.PageBackground/g' \
    -e 's/Editor\.EstimatedSize\b/Editor.FileSizeBadge/g' \
    -e 's/Editor\.ProgressOverlay\b/Editor.GenerationProgress/g' \
    -e 's/Editor\.AddSectionButton\b/Editor.AddImageButton/g' \
    -e 's/Editor\.PageList\b/Editor.Pages/g' \
    -e 's/Editor\.PageThumb\b/Editor.PageThumbnail/g'

(Drop the empty '' after -i on Linux - that's the BSD-sed form macOS uses.)

Swap `minimal-dark.css` import

git ls-files '*.ts' '*.tsx' '*.css' '*.mdx' \
  | xargs sed -i '' \
    -e "s|@docmosaic/react/styles/themes/minimal-dark.css|@docmosaic/react/styles.css|g"

Then add <ThemeProvider attribute="class"> (or your own .dark-class toggle) around the editor tree.

CSS variables and `--editor-color-*` aliases

The legacy --editor-color-* CSS aliases (--editor-color-accent, --editor-color-accent-soft, --editor-color-success, --editor-color-warning, --editor-color-warning-soft, --editor-color-surface, --editor-color-text) are still defined in v1.0 for back-compat. They resolve to the shadcn-aligned semantic surface (--primary, --secondary, --accent, --destructive, --background, --foreground) and will keep working.

New code should prefer the semantic surface directly - var(--primary) instead of var(--editor-color-accent), and so on. These aliases - along with the editor-* Tailwind color classes - are removed in v2.0.

Legacy alias	Semantic equivalent
`--editor-color-accent`	`--primary`
`--editor-color-accent-soft`	`--secondary`
`--editor-color-success`	`--accent`
`--editor-color-warning`	`--destructive`
`--editor-color-warning-soft`	(no semantic equivalent - caramel `#FFA552`)
`--editor-color-surface`	`--background`
`--editor-color-text`	`--foreground`

The structural tokens --editor-radius-section and --editor-shadow-section are kept - they're domain-specific and have no shadcn equivalent.

`@docmosaic/core`

No exported APIs were removed in v1.0. The 0.x line never shipped deprecated core aliases that survived past 0.1.0 - ImageSection, PDFDocument, createInitialDocument, createNewImageSection, createNewPage were already removed in earlier preview phases.

Questions?

Open an issue on GitHub if you hit anything not covered here.

Migrating to v1.0

On this page