@fileverse-dev/ddoc 5.1.9 → 6.0.0-drop-in.0

package/README.md

@@ -2,7 +2,7 @@
 [ddocs.new](http://ddocs.new/) is your privacy-focused, open-source alternative to Google Docs. It is an end-to-end encrypted document editor that is optimized for multiplayer collaboration without compromising on speed or people's control over their data.
 
 ## 𓆏 Features include:
-- End-to-end encryption
+- End-to-end encryption with post-quantum cryptography
 - Real-time and async collaboration
 - Suggestion mode (tracked changes) and commenting
 - Markdown and LaTeX support
@@ -46,6 +46,32 @@ import 'katex/dist/katex.min.css';      // math; fonts are served as files
 import '@fileverse-dev/ddoc/styles';    // editor CSS
 ```
 
+### Sizing
+
+`DdocEditor` fills its parent: `width: 100%; height: 100%`. The parent must have a definite height. The editor never reads the viewport, so a navbar above it or a footer below it is ordinary layout:
+
+```tsx
+<div style={{ height: '100dvh', display: 'flex', flexDirection: 'column' }}>
+  <div style={{ flex: 1, minHeight: 0 }}>
+    <DdocEditor renderNavbar={renderNavbar} />
+  </div>
+  <footer>…</footer>
+</div>
+```
+
+If the editor renders with no height, its parent has none.
+
+`renderNavbar` output is the editor's first row by default. Without `renderNavbar` no navbar element is rendered. To place the navbar elsewhere, pass the element to render into. Hold it in state, not in a ref, so the editor re-renders when it attaches:
+
+```tsx
+const [navbarEl, setNavbarEl] = useState<HTMLElement | null>(null);
+
+<header ref={setNavbarEl} />
+<DdocEditor navbarContainer={navbarEl} renderNavbar={renderNavbar} />
+```
+
+The layout follows the editor's width, not the window's: in a narrow panel it uses its narrow layout. Known limits: one `DdocEditor` per page; in a narrow editor on a wide screen the comment sheet still covers the whole viewport.
+
 ### Peer Dependencies
 
 This package requires the following peer dependencies to be installed in your project:
@@ -120,6 +146,28 @@ The preset composes `@fileverse/ui/tailwind` (class-based dark mode, animate plu
 
 You should now be set to use dDocs!
 
+### Migrating from 5.x
+
+6.0 changes how the editor is sized. No prop was removed.
+
+- Give the editor a parent with a definite height (see Sizing). It no longer sizes itself from `100dvh`.
+- Put your footer after the editor in normal flow. `footerHeight` has no effect and can be removed.
+- The navbar and toolbars are no longer inside `#editor-canvas`. CSS that used `#editor-canvas` as their ancestor should use `.ddoc-editor-root`.
+- Without `renderNavbar` the editor renders no navbar element at all. The navbar's height now comes from its content; it was a fixed 64px, 46px below `lg`.
+- `editorCanvasClassNames` should not set a height.
+- `zoomLevel`, `isNavbarVisible` and `isPreviewMode` are optional. Every UI state can be left out, or controlled with a value and an `onXChange` callback. The `setX` props still work and are deprecated.
+- Your Tailwind build needs no config change. The new `ddoc-*` variants (container-query breakpoints that follow the editor's width) come from the `@fileverse-dev/ddoc/tailwind` preset you already use.
+
+Behaviour that changes without a code change on your side:
+
+- UI features that did nothing without their `setX` prop now work on internal state. The Split View toggle shows whenever live collaboration is off (it needed `setIsSplitView` before), and the comment drawer, the outline and presentation mode open without a setter. To keep one fixed, pass its value with no callback, for example `isPresentationMode={false}`. For Split View, `isSplitView={false}` keeps the editor out of Split View, but the toolbar toggle is still shown and does nothing.
+- `onFocusModeChange` and the deprecated `onFocusMode` also fire when `isFocusMode` is not passed.
+- `#editor-canvas` is now the document scroller (it carries `data-editor-scroll-container`), and the root (`.ddoc-editor-root`) is `overflow: hidden`.
+- A navbar portalled with `navbarContainer` is positioned and layered by you; the editor only renders into the element.
+- The navbar and toolbars no longer slide or fade when hidden; their rows are removed and the canvas takes the space.
+- The mobile tab panel sits at the editor's bottom edge. It no longer adds `24px + env(safe-area-inset-bottom)`, so your footer must carry the safe-area inset.
+- The editor's responsive classes use `:where()` in their window fallback, so they need Chrome 88+, Safari 14+ or Firefox 78+.
+
 # dDocProps Interface
 
 The `DdocProps` interface is a TypeScript interface that defines the properties for a page-related component. It includes properties for handling preview mode, managing publishing data, and optionally storing metadata and content associated with the page.
@@ -131,7 +179,7 @@ The `DdocProps` interface is a TypeScript interface that defines the properties
 | `initialContent`         | `JSONContent`                                 | Initial content of the editor                   |
 | `onChange`               | `(changes: JSONContent, chunk?: any) => void` | Callback triggered on editor content changes    |
 | `ref`                    | `React.RefObject`                             | Reference to access editor instance             |
-| `isPreviewMode`          | `boolean`                                     | Controls if editor is in preview/read-only mode |
+| `isPreviewMode`          | `boolean`                                     | Controls if editor is in preview/read-only mode. Optional, defaults to `false` |
 | `editorCanvasClassNames` | `string`                                      | Additional CSS classes for editor canvas        |
 | `ignoreCorruptedData`    | `boolean`                                     | Whether to ignore corrupted data during loading |
 | `onInvalidContentError`  | `(error: any) => void`                        | Callback for handling invalid content errors    |
@@ -151,19 +199,40 @@ The `DdocProps` interface is a TypeScript interface that defines the properties
 
 ## UI/UX Props
 
-| Property                | Type                                      | Description                            |
-| ----------------------- | ----------------------------------------- | -------------------------------------- |
-| `zoomLevel`             | `string`                                  | Current zoom level of the editor       |
-| `setZoomLevel`          | `React.Dispatch<SetStateAction<string>>`  | Function to update zoom level          |
-| `isNavbarVisible`       | `boolean`                                 | Controls navbar visibility             |
-| `setIsNavbarVisible`    | `React.Dispatch<SetStateAction<boolean>>` | Function to toggle navbar visibility   |
-| `renderNavbar`          | `() => JSX.Element`                       | Custom navbar renderer                 |
-| `renderThemeToggle`     | `() => JSX.Element`                       | Custom theme toggle renderer           |
-| `isPresentationMode`    | `boolean`                                 | Controls presentation mode             |
-| `setIsPresentationMode` | `React.Dispatch<SetStateAction<boolean>>` | Function to toggle presentation mode   |
-| `sharedSlidesLink`      | `string`                                  | Link for shared presentation slides    |
-| `documentStyling`       | `DocumentStyling`                         | Custom styling for document appearance |
-| `fonts`                 | `FontDescriptor[]`                        | Consumer-provided font catalog (see Custom Fonts) |
+Every UI state can be left out (the editor keeps it internally), or controlled with a value and an `onXChange` callback. The `setX` props still work and are deprecated.
+
+| Property                    | Type                                      | Description                                                                         |
+| --------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------- |
+| `zoomLevel`                 | `string`                                  | Current zoom level of the editor. Optional, defaults to `'1'`                       |
+| `onZoomLevelChange`         | `(zoomLevel: string) => void`             | Zoom changed                                                                        |
+| `setZoomLevel`              | `React.Dispatch<SetStateAction<string>>`  | Deprecated, use `onZoomLevelChange`                                                 |
+| `isNavbarVisible`           | `boolean`                                 | Controls navbar visibility. Optional, defaults to `true`                            |
+| `onNavbarVisibleChange`     | `(visible: boolean) => void`              | Navbar shown or hidden                                                              |
+| `setIsNavbarVisible`        | `React.Dispatch<SetStateAction<boolean>>` | Deprecated, use `onNavbarVisibleChange`                                             |
+| `renderNavbar`              | `() => JSX.Element`                       | Custom navbar renderer. Without it no navbar is rendered                            |
+| `navbarContainer`           | `HTMLElement \| null`                     | Element to render the navbar into. Omit for in-flow. `null` renders nothing until it attaches |
+| `renderThemeToggle`         | `() => JSX.Element`                       | Custom theme toggle renderer                                                        |
+| `showTOC`                   | `boolean`                                 | Controls the outline                                                                |
+| `onShowTOCChange`           | `(show: boolean) => void`                 | Outline shown or hidden                                                             |
+| `setShowTOC`                | `React.Dispatch<SetStateAction<boolean>>` | Deprecated, use `onShowTOCChange`                                                   |
+| `commentDrawerOpen`         | `boolean`                                 | Controls the comment drawer                                                         |
+| `onCommentDrawerOpenChange` | `(open: boolean) => void`                 | Comment drawer opened or closed                                                     |
+| `setCommentDrawerOpen`      | `React.Dispatch<SetStateAction<boolean>>` | Deprecated, use `onCommentDrawerOpenChange`                                         |
+| `isPresentationMode`        | `boolean`                                 | Controls presentation mode                                                          |
+| `onPresentationModeChange`  | `(active: boolean) => void`               | Presentation mode entered or left                                                   |
+| `setIsPresentationMode`     | `React.Dispatch<SetStateAction<boolean>>` | Deprecated, use `onPresentationModeChange`                                          |
+| `isSplitView`               | `boolean`                                 | Controls Split View                                                                 |
+| `onSplitViewChange`         | `(active: boolean) => void`               | Split View entered or left                                                          |
+| `setIsSplitView`            | `React.Dispatch<SetStateAction<boolean>>` | Deprecated, use `onSplitViewChange`                                                 |
+| `isFocusMode`               | `boolean`                                 | Controls focus mode                                                                 |
+| `onFocusModeChange`         | `(isFocusMode: boolean) => void`          | Focus mode changed                                                                  |
+| `onFocusMode`               | `(isFocusMode: boolean) => void`          | Deprecated, use `onFocusModeChange`                                                 |
+| `onStatsChange`             | `(stats: { words; characters; selectedWords; pages: number \| null }) => void` | Active-tab stats; fires when any field changes. `pages` is `null` until measured |
+| `setWordCount`, `setCharacterCount`, `setSelectedWordCount`, `setPageCount` | `React.Dispatch<SetStateAction<number>>` | Deprecated, use `onStatsChange` |
+| `footerHeight`              | `string`                                  | Deprecated, no effect. Put the footer after the editor in normal flow               |
+| `sharedSlidesLink`          | `string`                                  | Link for shared presentation slides                                                 |
+| `documentStyling`           | `DocumentStyling`                         | Custom styling for document appearance                                              |
+| `fonts`                     | `FontDescriptor[]`                        | Consumer-provided font catalog (see Custom Fonts)                                   |
 
 ## Document Styling
 
@@ -283,7 +352,8 @@ const fonts: FontDescriptor[] = [
 | `onCommentReply`       | `(id: string, reply: IComment) => void` | Callback for comment replies       |
 | `onNewComment`         | `(comment: IComment) => void`           | Callback for new comments          |
 | `commentDrawerOpen`    | `boolean`                               | Controls comment drawer visibility |
-| `setCommentDrawerOpen` | `(isOpen: boolean) => void`             | Function to toggle comment drawer  |
+| `onCommentDrawerOpenChange` | `(open: boolean) => void`          | Comment drawer opened or closed    |
+| `setCommentDrawerOpen` | `(isOpen: boolean) => void`             | Deprecated, use `onCommentDrawerOpenChange` |
 | `onResolveComment`     | `(commentId: string) => void`           | Callback when resolving comments   |
 | `onUnresolveComment`   | `(commentId: string) => void`           | Callback when unresolving comments |
 | `onDeleteComment`      | `(commentId: string) => void`           | Callback when deleting comments    |
@@ -303,9 +373,9 @@ const fonts: FontDescriptor[] = [
 
 | Property            | Type                                                                     | Description                               |
 | ------------------- | ------------------------------------------------------------------------ | ----------------------------------------- |
-| `setCharacterCount` | `React.Dispatch<SetStateAction<number>>`                                 | Updates character count                   |
-| `setWordCount`      | `React.Dispatch<SetStateAction<number>>`                                 | Updates word count                        |
-| `setPageCount`      | `React.Dispatch<SetStateAction<number>>`                                 | Updates approx. export page count         |
+| `setCharacterCount` | `React.Dispatch<SetStateAction<number>>`                                 | Deprecated, use `onStatsChange`. Updates character count |
+| `setWordCount`      | `React.Dispatch<SetStateAction<number>>`                                 | Deprecated, use `onStatsChange`. Updates word count |
+| `setPageCount`      | `React.Dispatch<SetStateAction<number>>`                                 | Deprecated, use `onStatsChange`. Updates approx. export page count |
 | `ensResolutionUrl`  | `string`                                                                 | URL for ENS name resolution               |
 | `ipfsImageUploadFn` | ` (file: File) => Promise<IpfsImageUploadResponse>`                      | function for secure image uploads         |
 | `ipfsImageFetchFn`  | ` (_data: IpfsImageFetchPayload) => Promise<{ url: string;file: File;}>` | function for fetch secure image from IPFS |

package/dist/headless-editor-utils.es.js

@@ -1,8 +1,8 @@
-import { cc as s } from "./use-headless-editor-tZq6fxul.mjs";
-const c = (e) => {
+import { ce as s } from "./use-headless-editor-Buqsz3UI.mjs";
+const n = (e) => {
   const { getYjsConvertor: t, mergeYjsUpdates: r } = s(e);
   return { getYjsConvertor: t, mergeYjsUpdates: r };
 };
 export {
-  c as createHeadlessSyncRuntime
+  n as createHeadlessSyncRuntime
 };

package/dist/{index-DtE1zaH8.mjs → index-8MQH4TSF.mjs}

@@ -1,4 +1,4 @@
-import { cd as Ql, ce as Zl, cf as eh } from "./use-headless-editor-tZq6fxul.mjs";
+import { cf as Ql, cg as Zl, ch as eh } from "./use-headless-editor-Buqsz3UI.mjs";
 let An = [], Xr = [];
 (() => {
   let s = "lc,34,7n,7,7b,19,,,,2,,2,,,20,b,1c,l,g,,2t,7,2,6,2,2,,4,z,,u,r,2j,b,1m,9,9,,o,4,,9,,3,,5,17,3,3b,f,,w,1j,,,,4,8,4,,3,7,a,2,t,,1m,,,,2,4,8,,9,,a,2,q,,2,2,1l,,4,2,4,2,2,3,3,,u,2,3,,b,2,1l,,4,5,,2,4,,k,2,m,6,,,1m,,,2,,4,8,,7,3,a,2,u,,1n,,,,c,,9,,14,,3,,1l,3,5,3,,4,7,2,b,2,t,,1m,,2,,2,,3,,5,2,7,2,b,2,s,2,1l,2,,,2,4,8,,9,,a,2,t,,20,,4,,2,3,,,8,,29,,2,7,c,8,2q,,2,9,b,6,22,2,r,,,,,,1j,e,,5,,2,5,b,,10,9,,2u,4,,6,,2,2,2,p,2,4,3,g,4,d,,2,2,6,,f,,jj,3,qa,3,t,3,t,2,u,2,1s,2,,7,8,,2,b,9,,19,3,3b,2,y,,3a,3,4,2,9,,6,3,63,2,2,,1m,,,7,,,,,2,8,6,a,2,,1c,h,1r,4,1c,7,,,5,,14,9,c,2,w,4,2,2,,3,1k,,,2,3,,,3,1m,8,2,2,48,3,,d,,7,4,,6,,3,2,5i,1m,,5,ek,,5f,x,2da,3,3x,,2o,w,fe,6,2x,2,n9w,4,,a,w,2,28,2,7k,,3,,4,,p,2,5,,47,2,q,i,d,,12,8,p,b,1a,3,1c,,2,4,2,2,13,,1v,6,2,2,2,2,c,,8,,1b,,1f,,,3,2,2,5,2,,,16,2,8,,6m,,2,,4,,fn4,,kh,g,g,g,a6,2,gt,,6a,,45,5,1ae,3,,2,5,4,14,3,4,,4l,2,fx,4,ar,2,49,b,4w,,1i,f,1k,3,1d,4,2,2,1x,3,10,5,,8,1q,,c,2,1g,9,a,4,2,,2n,3,2,,,2,6,,4g,,3,8,l,2,1l,2,,,,,m,,e,7,3,5,5f,8,2,3,,,n,,29,,2,6,,,2,,,2,,2,6j,,2,4,6,2,,2,r,2,2d,8,2,,,2,2y,,,,2,6,,,2t,3,2,4,,5,77,9,,2,6t,,a,2,,,4,,40,4,2,2,4,,w,a,14,6,2,4,8,,9,6,2,3,1a,d,,2,ba,7,,6,,,2a,m,2,7,,2,,2,3e,6,3,,,2,,7,,,20,2,3,,,,9n,2,f0b,5,1n,7,t4,,1r,4,29,,f5k,2,43q,,,3,4,5,8,8,2,7,u,4,44,3,1iz,1j,4,1e,8,,e,,m,5,,f,11s,7,,h,2,7,,2,,5,79,7,c5,4,15s,7,31,7,240,5,gx7k,2o,3k,6o".split(",").map((e) => e ? parseInt(e, 36) : 1);

package/dist/index.d.ts

@@ -19,6 +19,6 @@ export type { CollaborationProps, CollabConnectionConfig, CollabSessionMeta, Col
 export { encryptForRoomKey, decryptForRoomKey, } from './package/sync-local/crypto/room-key';
 export { WIRE_TAG, isXChaChaCipher } from './package/sync-local/crypto';
 export { fetchSessionState, seedSession, } from './package/sync-local/session-tools';
-export type { CommentMutationMeta, SuggestionType } from './package/types';
+export type { CommentMutationMeta, DdocStats, SuggestionType, } from './package/types';
 export type { IComment } from './package/extensions/comment/comment.ts';
 export type { FontDescriptor } from './package/types';