deepspace 0.3.9 → 0.3.11

package/features/docs/src/docs-ui.css

@@ -0,0 +1,309 @@
+/**
+ * Docs feature UI — derives palette from the host app's design tokens (--color-* on
+ * shadcn/Tailwind starters, --theme-* / --ui-* when DeepSpaceThemeProvider applies a theme).
+ * No separate light/dark block: inherits whatever the root provides (e.g. [data-theme] changes).
+ */
+
+.docs-feature-scope {
+  --docs-el-bg: var(--color-background, var(--theme-background, #fafafa));
+  --docs-el-surface: var(
+    --color-card,
+    var(--theme-library-card-bg, var(--theme-panel-bg, #ffffff))
+  );
+  --docs-el-text: var(--color-foreground, var(--theme-text, #1d1d1f));
+  --docs-el-muted: var(
+    --color-muted-foreground,
+    var(--theme-text-secondary, var(--theme-text-tertiary, #86868b))
+  );
+  --docs-el-accent: var(--color-primary, var(--theme-accent, var(--ui-accent, #3b82f6)));
+  --docs-el-line: var(--color-border, var(--theme-border, rgba(15, 23, 42, 0.12)));
+
+  --docs-el-selection: var(
+    --color-primary-muted,
+    color-mix(in srgb, var(--docs-el-accent) 22%, transparent)
+  );
+
+  --docs-editor-desk: var(
+    --color-muted,
+    var(
+      --theme-library-surface,
+      var(--theme-surface-solid, var(--theme-surface, var(--docs-el-bg)))
+    )
+  );
+  --docs-editor-paper: #ffffff;
+  --docs-editor-paper-text: #111111;
+  --docs-editor-paper-muted: #6b7280;
+  --docs-editor-paper-border: var(--docs-el-line);
+  --docs-editor-paper-shadow: var(
+    --shadow-card,
+    var(--ui-shadow-md, 0 4px 12px rgba(15, 23, 42, 0.08))
+  );
+}
+
+/*
+ * Editor text selection ("cursor highlight") is intentionally NOT themed:
+ *   - Background uses a stable blue so the selection always reads as a
+ *     selection — themes whose accent is yellow/red don't make selection
+ *     look like a highlighter mark.
+ *   - `color: inherit` is REQUIRED, not optional. Browsers (Chromium, Safari,
+ *     Firefox) all repaint selected text in their own default contrast color
+ *     — usually white — when you set a `::selection` background without an
+ *     explicit `color`. That's what made selected text turn white. Forcing
+ *     `color: inherit` keeps the underlying text in its own color (default
+ *     black on the paper, or whatever the user picked via the text-color
+ *     toolbar).
+ *   - `-webkit-text-fill-color: inherit` is the same fix for Safari, which
+ *     would otherwise still override `color` inside `::selection`.
+ */
+.docs-paged-editor .ProseMirror ::selection,
+.docs-paged-editor .ProseMirror::selection {
+  background-color: #6aa8f3;
+  color: inherit;
+  -webkit-text-fill-color: inherit;
+}
+
+.docs-editor-paper {
+  background-color: var(--docs-editor-paper);
+  border: 1px solid var(--docs-editor-paper-border);
+  box-shadow: var(--docs-editor-paper-shadow);
+}
+
+.docs-paged-editor-canvas {
+  background-color: var(--docs-editor-desk);
+}
+
+.docs-presence-avatar,
+.docs-presence-more {
+  align-items: center;
+  background-color: color-mix(in srgb, var(--docs-el-accent) 14%, var(--docs-el-surface));
+  border: 2px solid var(--docs-el-surface);
+  border-radius: 9999px;
+  color: var(--docs-el-text);
+  display: inline-flex;
+  flex: none;
+  font-size: 11px;
+  font-weight: 700;
+  height: 30px;
+  justify-content: center;
+  line-height: 1;
+  overflow: hidden;
+  width: 30px;
+}
+
+.docs-presence-more {
+  cursor: pointer;
+  transition:
+    background-color 160ms ease,
+    color 160ms ease;
+}
+
+.docs-presence-more:hover {
+  background-color: color-mix(in srgb, var(--docs-el-accent) 22%, var(--docs-el-surface));
+  color: var(--docs-el-accent);
+}
+
+.docs-paged-page-padding {
+  --docs-pad-v: 0.42in;
+  --docs-pad-h: 0.38in;
+  padding: var(--docs-pad-v) var(--docs-pad-h);
+}
+
+@media (min-width: 640px) {
+  .docs-paged-page-padding {
+    --docs-pad-v: 0.55in;
+    --docs-pad-h: 0.65in;
+  }
+}
+
+@media (min-width: 1024px) {
+  .docs-paged-page-padding {
+    --docs-pad-v: 0.62in;
+    --docs-pad-h: 0.75in;
+  }
+}
+
+.docs-paged-editor-font {
+  font-size: 11pt;
+  line-height: 1.4;
+  color: var(--docs-editor-paper-text);
+}
+
+@media (max-width: 640px) {
+  .docs-paged-editor-font {
+    font-size: 16px;
+    line-height: 1.6;
+  }
+}
+
+/* Tiptap ProseMirror canvas */
+.docs-paged-editor .ProseMirror,
+.docs-paged-editor .tiptap.ProseMirror,
+.docs-paged-editor .docs-tiptap-editor {
+  outline: none;
+  min-height: 1.6em;
+  caret-color: #000;
+  color: var(--docs-editor-paper-text);
+}
+
+.docs-paged-editor .ProseMirror p,
+.docs-paged-editor .ProseMirror li,
+.docs-paged-editor .ProseMirror h1,
+.docs-paged-editor .ProseMirror h2,
+.docs-paged-editor .ProseMirror h3,
+.docs-paged-editor .ProseMirror h4,
+.docs-paged-editor .ProseMirror h5,
+.docs-paged-editor .ProseMirror h6 {
+  margin: 0 0 0.45em;
+}
+
+.docs-paged-editor .ProseMirror h1 {
+  font-size: 1.9em;
+  font-weight: 700;
+  line-height: 1.2;
+  margin-top: 0.2em;
+}
+.docs-paged-editor .ProseMirror h2 {
+  font-size: 1.5em;
+  font-weight: 700;
+  line-height: 1.25;
+  margin-top: 0.15em;
+}
+.docs-paged-editor .ProseMirror h3 {
+  font-size: 1.25em;
+  font-weight: 600;
+  line-height: 1.3;
+}
+
+.docs-paged-editor .ProseMirror blockquote {
+  border-left: 3px solid var(--docs-el-line);
+  margin: 0.5em 0;
+  padding: 0.1em 0.85em;
+  color: var(--docs-editor-paper-muted);
+}
+
+.docs-paged-editor .ProseMirror ul,
+.docs-paged-editor .ProseMirror ol {
+  padding-left: 1.4em;
+  margin: 0 0 0.45em;
+}
+
+.docs-paged-editor .ProseMirror ul[data-type='taskList'] {
+  list-style: none;
+  padding: 0;
+}
+
+.docs-paged-editor .ProseMirror ul[data-type='taskList'] li {
+  align-items: flex-start;
+  display: flex;
+  gap: 0.5em;
+}
+
+.docs-paged-editor .ProseMirror ul[data-type='taskList'] li > label {
+  flex: none;
+  margin-top: 0.25em;
+}
+
+.docs-paged-editor .ProseMirror hr {
+  border: none;
+  border-top: 1px solid var(--docs-el-line);
+  margin: 1em 0;
+}
+
+.docs-paged-editor .ProseMirror a {
+  color: var(--docs-el-accent);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.docs-paged-editor .ProseMirror code {
+  background-color: color-mix(in srgb, var(--docs-el-muted) 14%, transparent);
+  border-radius: 3px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
+  font-size: 0.9em;
+  padding: 0.1em 0.3em;
+}
+
+.docs-paged-editor .ProseMirror mark,
+.docs-paged-editor .ProseMirror .docs-text-highlight {
+  background-color: #bfdbfe;
+  color: var(--docs-editor-paper-text);
+}
+
+.docs-paged-editor .ProseMirror mark *,
+.docs-paged-editor .ProseMirror .docs-text-highlight * {
+  color: var(--docs-editor-paper-text) !important;
+}
+
+/* Placeholder (from @tiptap/extension-placeholder) — applied to the first empty paragraph. */
+.docs-paged-editor .ProseMirror p.is-editor-empty:first-child::before {
+  color: var(--docs-editor-paper-muted);
+  content: attr(data-placeholder);
+  float: left;
+  height: 0;
+  pointer-events: none;
+}
+
+/* Soft page break: decoration spacer that fills the rest of the current page. */
+.docs-soft-page-break {
+  display: block;
+  flex: none;
+  width: 100%;
+  pointer-events: none;
+  user-select: none;
+}
+
+@media print {
+  .docs-soft-page-break {
+    display: none !important;
+  }
+}
+
+/* CollaborationCaret — remote cursor & label rendered by the extension. */
+.collaboration-carets__caret {
+  border-left: 1px solid var(--collaboration-caret-color, #2563eb);
+  border-right: 1px solid var(--collaboration-caret-color, #2563eb);
+  margin-left: -1px;
+  margin-right: -1px;
+  pointer-events: none;
+  position: relative;
+  word-break: normal;
+}
+
+.collaboration-carets__label {
+  border-radius: 3px;
+  color: #111111;
+  font-size: 11px;
+  font-weight: 600;
+  font-style: normal;
+  left: -1px;
+  letter-spacing: 0.01em;
+  line-height: 1;
+  padding: 0.1em 0.35em;
+  position: absolute;
+  top: -1.4em;
+  user-select: none;
+  white-space: nowrap;
+}
+
+.ProseMirror-yjs-selection,
+.collaboration-carets__selection {
+  border-radius: 1px;
+}
+
+/*
+ * Print: the on-screen editor inherits the host theme's foreground color via
+ * --docs-el-text (often a light gray on dark themes), but the print canvas is
+ * forced to white. Without this override, the printed page comes out blank.
+ */
+@media print {
+  .docs-paged-page-face {
+    background-color: #ffffff !important;
+  }
+  .docs-paged-editor {
+    color: var(--docs-editor-paper-text) !important;
+  }
+  .collaboration-carets__caret,
+  .collaboration-carets__label {
+    display: none !important;
+  }
+}

package/features/docs/src/editor/DocEditorSurface.tsx

@@ -0,0 +1,257 @@
+/**
+ * Paged editor surface — Letter-sized, decoration-based pagination.
+ *
+ * The ProseMirror document stays as one collaborative document. Pagination is
+ * a view-only layer: we measure rendered text, insert ProseMirror Decoration
+ * widgets at the calculated page boundaries (spacer divs filling the rest of
+ * each sheet), and render absolutely-positioned "page face" backgrounds
+ * behind the content. The Yjs document is never touched.
+ *
+ * Decorations are a no-op for the CRDT, so adding/removing page breaks
+ * never produces a Yjs update, never re-syncs, and never moves a remote
+ * collaborator's caret.
+ */
+
+import { useCallback, useLayoutEffect, useRef, useState } from 'react'
+import { EditorContent, type Editor } from '@tiptap/react'
+import { Decoration, DecorationSet } from '@tiptap/pm/view'
+
+const PX_PER_IN = 96
+const PAGE_W_IN = 8.5
+const PAGE_H_IN = 11
+export const PAGE_HEIGHT_PX = Math.round(PAGE_H_IN * PX_PER_IN)
+export const PAGE_WIDTH_PX = Math.round(PAGE_W_IN * PX_PER_IN)
+export const GAP_PX = 24
+const PAGE_STRIDE_PX = PAGE_HEIGHT_PX + GAP_PX
+const PAGE_EPSILON_PX = 3
+const MAX_SOFT_PAGE_BREAKS = 80
+const PAGINATION_UPDATE_DELAY_MS = 180
+
+export const TYPICAL_WORDS_PER_PAGE = 480
+
+type SoftPageBreak = {
+  pos: number
+  height: number
+}
+
+function pageCountForBodyHeight(bodyHeight: number, pageBodyHeight: number) {
+  let pages = 1
+  while (bodyHeight > (pages - 1) * PAGE_STRIDE_PX + pageBodyHeight + PAGE_EPSILON_PX) {
+    pages += 1
+  }
+  return pages
+}
+
+function makeSoftPageBreakDecorations(editor: Editor, breaks: SoftPageBreak[]) {
+  if (breaks.length === 0) return DecorationSet.empty
+
+  const docSize = editor.state.doc.content.size
+  return DecorationSet.create(
+    editor.state.doc,
+    breaks.map((pageBreak, index) =>
+      Decoration.widget(
+        Math.min(pageBreak.pos, docSize),
+        () => {
+          const spacer = document.createElement('span')
+          spacer.className = 'docs-soft-page-break'
+          spacer.style.height = `${pageBreak.height}px`
+          spacer.contentEditable = 'false'
+          spacer.setAttribute('aria-hidden', 'true')
+          return spacer
+        },
+        {
+          key: `docs-page-break-${index}-${pageBreak.pos}-${Math.round(pageBreak.height)}`,
+          side: 1,
+          ignoreSelection: true,
+        },
+      ),
+    ),
+  )
+}
+
+type DocEditorSurfaceProps = {
+  editor: Editor
+  onPageCountChange?: (n: number) => void
+}
+
+export function DocEditorSurface({ editor, onPageCountChange }: DocEditorSurfaceProps) {
+  const [pageCount, setPageCount] = useState(1)
+  const pageBreaksRef = useRef<SoftPageBreak[]>([])
+  const rafRef = useRef<number | undefined>(undefined)
+  const recalcTimerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+
+  const report = useCallback(
+    (n: number) => {
+      onPageCountChange?.(n)
+      setPageCount((prev) => (prev === n ? prev : n))
+    },
+    [onPageCountChange],
+  )
+
+  useLayoutEffect(() => {
+    const view = editor.view
+    const dom = view?.dom
+    if (!dom) return
+
+    /**
+     * `useEditor` destroys+recreates the Tiptap editor whenever the
+     * `extensions` array identity changes — notably when the owner toggles
+     * this peer between editor and viewer, since the placeholder string
+     * flips on `showReadOnlyDocUx`. The destroy nulls the ProseMirror
+     * `docView` internally; any rAF / timeout / ResizeObserver that fires
+     * afterwards and still calls `view.dispatch` or `view.setProps` lands
+     * in `updateStateInner` and throws
+     * `Cannot read properties of null (reading 'matchesNode')`, killing
+     * the route. `editor.isDestroyed` is the supported signal — set the
+     * moment Tiptap tears the editor down — so we use it to short-circuit
+     * every async callback rooted in this effect.
+     */
+    const viewIsAlive = () => !editor.isDestroyed
+
+    const previousDecorations = view.props.decorations
+    const refreshDecorations = () => {
+      if (!viewIsAlive()) return
+      view.dispatch(
+        view.state.tr.setMeta('addToHistory', false).setMeta('docsPagination', true),
+      )
+    }
+
+    view.setProps({
+      decorations: (state) => {
+        const externalDecorations =
+          typeof previousDecorations === 'function'
+            ? previousDecorations(state)
+            : previousDecorations
+        const pageDecorations = makeSoftPageBreakDecorations(editor, pageBreaksRef.current)
+
+        if (!externalDecorations) return pageDecorations
+        const externalDecorationItems: Decoration[] = []
+        externalDecorations.forEachSet((set) => {
+          externalDecorationItems.push(...set.find())
+        })
+        return DecorationSet.create(state.doc, [
+          ...externalDecorationItems,
+          ...pageDecorations.find(),
+        ])
+      },
+    })
+
+    const recalc = () => {
+      if (recalcTimerRef.current !== undefined) {
+        clearTimeout(recalcTimerRef.current)
+        recalcTimerRef.current = undefined
+      }
+      if (rafRef.current !== undefined) cancelAnimationFrame(rafRef.current)
+      rafRef.current = requestAnimationFrame(() => {
+        rafRef.current = undefined
+        if (!viewIsAlive()) return
+        const shell = dom.closest<HTMLElement>('.docs-paged-content')
+        if (!shell) return
+
+        const shellStyle = window.getComputedStyle(shell)
+        const paddingTop = Number.parseFloat(shellStyle.paddingTop) || 0
+        const paddingBottom = Number.parseFloat(shellStyle.paddingBottom) || 0
+        const pageBodyHeight = PAGE_HEIGHT_PX - paddingTop - paddingBottom
+
+        pageBreaksRef.current = []
+        refreshDecorations()
+
+        let lastBreakPos = -1
+        for (let pageIndex = 0; pageIndex < MAX_SOFT_PAGE_BREAKS; pageIndex += 1) {
+          if (!viewIsAlive()) return
+          const bodyHeight = dom.scrollHeight
+          const pageBottom = pageIndex * PAGE_STRIDE_PX + pageBodyHeight
+          if (bodyHeight <= pageBottom + PAGE_EPSILON_PX) break
+
+          const domRect = dom.getBoundingClientRect()
+          const posAtBoundary = view.posAtCoords({
+            left: domRect.right - 2,
+            top: domRect.top + pageBottom - 2,
+          })
+
+          if (!posAtBoundary || posAtBoundary.pos <= lastBreakPos) break
+
+          const coords = view.coordsAtPos(posAtBoundary.pos)
+          const breakY = Math.max(coords.bottom - domRect.top, pageIndex * PAGE_STRIDE_PX)
+          const breakHeight = Math.max(0, (pageIndex + 1) * PAGE_STRIDE_PX - breakY)
+
+          if (breakHeight <= PAGE_EPSILON_PX) break
+
+          lastBreakPos = posAtBoundary.pos
+          pageBreaksRef.current = [
+            ...pageBreaksRef.current,
+            { pos: posAtBoundary.pos, height: breakHeight },
+          ]
+          refreshDecorations()
+        }
+
+        if (!viewIsAlive()) return
+        const pagedBodyHeight = dom.scrollHeight
+        const measuredPages = pageCountForBodyHeight(pagedBodyHeight, pageBodyHeight)
+        report(measuredPages)
+      })
+    }
+    const scheduleRecalc = () => {
+      if (recalcTimerRef.current !== undefined) clearTimeout(recalcTimerRef.current)
+      recalcTimerRef.current = setTimeout(() => {
+        recalcTimerRef.current = undefined
+        if (!viewIsAlive()) return
+        recalc()
+      }, PAGINATION_UPDATE_DELAY_MS)
+    }
+
+    const ro = new ResizeObserver(() => {
+      if (!viewIsAlive()) return
+      recalc()
+    })
+    ro.observe(dom)
+    recalc()
+    editor.on('update', scheduleRecalc)
+
+    return () => {
+      if (recalcTimerRef.current !== undefined) clearTimeout(recalcTimerRef.current)
+      if (rafRef.current !== undefined) cancelAnimationFrame(rafRef.current)
+      recalcTimerRef.current = undefined
+      rafRef.current = undefined
+      ro.disconnect()
+      editor.off('update', scheduleRecalc)
+      pageBreaksRef.current = []
+      if (!viewIsAlive()) return
+      view.setProps({ decorations: previousDecorations })
+      refreshDecorations()
+    }
+  }, [editor, report])
+
+  const stackHeight = pageCount * PAGE_HEIGHT_PX + Math.max(0, pageCount - 1) * GAP_PX
+
+  return (
+    <div className="docs-paged-editor-canvas h-full min-h-0 w-full flex-1 overflow-y-auto overflow-x-hidden overscroll-y-contain print:block print:!h-auto print:!overflow-visible print:!bg-white">
+      <div className="docs-paged-inner pointer-events-auto mx-auto w-full max-w-full px-2 py-3 sm:px-3 sm:py-4 md:py-5">
+        <div
+          className="docs-paged-page-frame relative mx-auto"
+          style={{ width: `${PAGE_W_IN}in`, maxWidth: '100%' }}
+        >
+          <div className="docs-paged-page-stack relative" style={{ minHeight: `${stackHeight}px` }}>
+            {Array.from({ length: pageCount }, (_, index) => (
+              <div
+                key={index}
+                className="docs-paged-page-face docs-editor-paper pointer-events-none absolute left-0 top-0 h-[11in] w-full rounded-sm print:static print:h-auto print:shadow-none print:border-0"
+                style={{ transform: `translateY(${index * PAGE_STRIDE_PX}px)` }}
+              />
+            ))}
+            <div
+              className="docs-paged-content docs-paged-page-padding relative z-10 box-border"
+              style={{ maxWidth: '100%', minHeight: `${stackHeight}px` }}
+            >
+              <EditorContent
+                editor={editor}
+                className="docs-paged-editor docs-paged-editor-font tiptap"
+                data-testid="editor-content"
+              />
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}