@docs.plus/extension-placeholder 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to `@docs.plus/extension-placeholder` are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/); the project adheres to [Semantic Versioning](https://semver.org/).
+
+## [2.0.0] — 2026-08-11
+
+### Highlights
+
+- **First npm publish** — versioned `2.0.0` to align with the docs.plus extension-family shared major.
+- **O(depth) cursor-based decoration** — decorates only the empty node at the cursor plus empty ancestor wrappers; no full-document `doc.descendants` scan on every keystroke.
+- **Runtime editable toggle** — `editor.setEditable()` refreshes the placeholder immediately when `showOnlyWhenEditable` is on.
+- **Clean-room Cypress suite** — twelve specs against built `dist/` on port 5177 (empty doc, cursor tracking, undo, full-doc paste, gap cursor).
+
+### Changed
+
+- `apply()` skips recomputation for meta-only transactions (neither doc nor selection changed).
+
+### Fixed
+
+- A non-text selection no longer puts `data-placeholder` on a wrapper node. `$anchor.parent` is a textblock only for a text selection. So a `NodeSelection` on an empty paragraph inside a blockquote or list item resolved to the wrapper and painted the placeholder on it. The guard now tests `node.type.isTextblock`.
+- `editor.setEditable()` refreshes the placeholder at runtime. With `showOnlyWhenEditable: true`, toggling read-only left a stale placeholder (or failed to restore it on re-enable): the editability gate lived in the plugin's `apply`, which `setEditable` does not re-run. The gate moved to `props.decorations`, which `view.updateState` re-runs.
+
+### Documentation
+
+- Documented the differences from the built-in Placeholder, pointed the CSS example at `.ProseMirror [data-placeholder]::before`, and added a screen-reader labeling note.
+
+### Internal
+
+- The published manifest no longer declares `engines` — the monorepo's Node floor gated engine-strict consumer installs even though the shipped bundle is plain browser-targeted ESM/CJS.
+- Added a clean-room Cypress E2E suite (`@docs.plus/playground`, port 5177) against the built `dist/`: empty-document lifecycle, cursor tracking, ancestor propagation, the editable toggle, option resolution, `isNodeEmpty` semantics, external edits, undo/redo, full-document paste, horizontal rule and gap cursor, per-node-type `placeholder` functions, and real-keystroke Backspace.
+- Replaced a cast with `?? null` in `props.decorations`.
+- Added a `typecheck` script; corrected "TipTap" to "Tiptap" in the package description.
+
+## [0.1.0]
+
+Pre-changelog baseline, never published to npm. O(depth) cursor-based placeholder decoration — decorates only the empty node at the cursor and its empty ancestor wrappers instead of scanning with Tiptap's built-in `doc.descendants`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-2026 Hossein Marzban
+
+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,250 @@
+# @docs.plus/extension-placeholder
+
+<a href="https://docs.plus"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/docs-plus/docs.plus/main/apps/webapp/public/badges/badge-docsplus-dark.svg"><img alt="docs.plus" height="20" src="https://raw.githubusercontent.com/docs-plus/docs.plus/main/apps/webapp/public/badges/badge-docsplus.svg"></picture></a>
+[![Version](https://img.shields.io/npm/v/@docs.plus/extension-placeholder.svg?label=version)](https://www.npmjs.com/package/@docs.plus/extension-placeholder)
+[![Downloads](https://img.shields.io/npm/dm/@docs.plus/extension-placeholder.svg)](https://npmcharts.com/compare/@docs.plus/extension-placeholder)
+[![License](https://img.shields.io/npm/l/@docs.plus/extension-placeholder.svg)](https://www.npmjs.com/package/@docs.plus/extension-placeholder)
+[![Discord](https://img.shields.io/badge/discord-community-5865F2?logo=discord&logoColor=white)](https://discord.gg/25JPG38J59)
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/docs-plus/docs.plus/main/extensions/extension-placeholder/assets/preview-dark.png">
+    <img alt="Empty editor showing placeholder hint text in the first paragraph" width="640" src="https://raw.githubusercontent.com/docs-plus/docs.plus/main/extensions/extension-placeholder/assets/preview-light.png">
+  </picture>
+</p>
+
+Tiptap placeholder extension that shows hint text in the empty textblock at the cursor.
+
+A textblock is a node that holds inline text, such as a paragraph or a heading. Tiptap's built-in Placeholder scans every top-level block with `doc.descendants` on every editor update, and the whole tree when `includeChildren` is on. This package starts at the cursor and walks up, so the cost tracks the cursor depth, not the document length. It writes the hint text into a `data-placeholder` attribute on the empty textblock at the cursor. It also adds `emptyNodeClass` to every empty ancestor wrapper above that textblock. It accepts four of the built-in's seven options, and its callback form gains `parentName` and `doc`.
+
+## Install
+
+```sh
+bun add @docs.plus/extension-placeholder
+```
+
+Requires **`@tiptap/core` ^3.22.3** and **`@tiptap/pm` ^3.22.3** (Tiptap 3.x).
+
+Installs with no runtime dependencies.
+
+To move from Tiptap's built-in Placeholder, see [Migrating from the built-in Placeholder](#migrating-from-the-built-in-placeholder).
+
+## Quickstart
+
+Register `Placeholder` in the extensions array and set the hint text.
+
+```ts
+import { Editor } from '@tiptap/core'
+import StarterKit from '@tiptap/starter-kit'
+import { Placeholder } from '@docs.plus/extension-placeholder'
+
+const editor = new Editor({
+  element: document.querySelector('#editor')!,
+  extensions: [
+    StarterKit,
+    // StarterKit does not include a placeholder extension.
+    // If your array already holds Tiptap's built-in Placeholder, remove it.
+    // Register one placeholder extension, never both.
+    Placeholder.configure({
+      placeholder: 'Write something …'
+    })
+  ]
+})
+```
+
+The snippet mounts the editor into `#editor`, so that element must exist on the page. The editor renders no hint yet, because the package ships no CSS — add the rule in [Styling](#styling).
+
+## Options
+
+`.configure({ … })` accepts these four options and nothing else.
+
+| Option                 | Type                                                    | Default               | Description                                                                                                             |
+| ---------------------- | ------------------------------------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `placeholder`          | `((props: PlaceholderRenderProps) => string) \| string` | `'Write something …'` | Hint text, or a callback that returns it per textblock. See [`placeholder`](#placeholder).                              |
+| `emptyNodeClass`       | `string`                                                | `'is-empty'`          | Class the extension adds to the empty textblock at the cursor, and to every empty ancestor wrapper above it.            |
+| `emptyEditorClass`     | `string`                                                | `'is-editor-empty'`   | Extra class next to `emptyNodeClass` while the whole document is empty. The extension never adds it to the editor root. |
+| `showOnlyWhenEditable` | `boolean`                                               | `true`                | Hides the hint and both classes while the editor is read-only.                                                          |
+
+The extension reads `showOnlyWhenEditable` at render time. `editor.setEditable()` therefore updates the hint and both classes at once, without a transaction.
+
+### `placeholder`
+
+A string sets one hint for every empty textblock. A callback sets the hint per textblock, and receives one object:
+
+- `node` — the empty textblock at the cursor.
+- `parentName` — type name of the parent node, for example `doc`, `listItem` or `blockquote`.
+- `pos` — position of `node` inside `doc`.
+- `doc` — the document the extension builds the decoration from.
+- `hasAnchor` — always `true`, because the extension decorates only the empty textblock at the cursor. See the `hasAnchor` note in [Migrating from the built-in Placeholder](#migrating-from-the-built-in-placeholder).
+- `editor` — the editor instance.
+
+The callback runs inside the plugin's `init()` and `apply()`. During `apply()` it runs before the editor commits the transaction, so resolve `pos` against the supplied `doc`, never `editor.state.doc`.
+
+To change the hint after the editor exists, use the callback form and read the new text inside it. Then force a rebuild with the dispatch in [Caveats](#caveats).
+
+```ts
+Placeholder.configure({
+  placeholder: ({ node, parentName }) => {
+    if (node.type.name === 'heading') return "What's the title?"
+    if (parentName === 'listItem') return 'List item'
+    if (parentName === 'blockquote') return 'Quote'
+    return 'Can you add some further context?'
+  }
+})
+```
+
+`node` names the empty textblock and `parentName` names its parent, so the two answer different questions. An empty paragraph inside a list item reports `node.type.name === 'paragraph'` and `parentName === 'listItem'`.
+
+A callback that returns `''` emits no decoration — see [Caveats](#caveats).
+
+## Caveats
+
+The extension adds at most one `data-placeholder` decoration per state, and it treats a node as empty only when `isNodeEmpty(node)` from `@tiptap/core` returns true.
+
+- **Nothing renders without CSS.** The package ships no stylesheet, and the extension writes the hint text into a `data-placeholder` attribute. Add the rule in [Styling](#styling).
+- **Two placeholder extensions collide.** This extension and Tiptap's built-in both register the name `placeholder`. Tiptap logs the warning `[tiptap warn]: Duplicate extension names found: ['placeholder']. This can lead to issues.`, and both plugins decorate the document.
+- **A single space counts as content.** The check is `isNodeEmpty(node)` with the default `ignoreWhitespace: false`. A paragraph holding one space, or one hard break, shows no hint.
+- **`showOnlyCurrent`, `includeChildren` and `dataAttribute` do not exist.** TypeScript rejects them in a `.configure({ … })` literal. A plain JavaScript host gets no error, and the extension ignores the key. The option map in [Migrating from the built-in Placeholder](#migrating-from-the-built-in-placeholder) gives the replacement for each one.
+- **An empty hint removes the classes too.** A `placeholder` string or callback that resolves to `''` emits no decoration, so `emptyNodeClass` and `emptyEditorClass` disappear as well. Return a placeholder string of one space to keep the classes without visible text.
+- **A selection at document depth hides the hint.** ⌘A or Ctrl+A produces an `AllSelection` whose anchor sits at that depth. A node selection on a top-level node does the same. The hint returns when the selection moves back into a textblock.
+- **The hint stays after blur.** Nothing in the extension reads `editor.isFocused`, so the decoration survives a blur. Hide it with a CSS rule — see [Styling](#styling).
+- **Do not rely on the hint for accessibility.** It is generated content on a `::before` pseudo-element, outside the document. Set `aria-label` or `aria-placeholder` on the editable element yourself.
+- **The callback runs only on a document or selection change.** The extension rebuilds when a transaction changes the document or sets the selection. Hint text from outside the document, i18n text for example, does not refresh on its own. Force a rebuild with `editor.view.dispatch(editor.state.tr.setSelection(editor.state.selection))`. The same rule keeps the hint stable under [Collaborative editing](#collaborative-editing).
+
+## Styling
+
+The package ships no CSS.
+
+The extension writes the resolved hint text into the `data-placeholder` attribute of the empty textblock at the cursor. Add this rule to render it:
+
+```css
+.ProseMirror [data-placeholder]::before {
+  content: attr(data-placeholder);
+  color: #9ca3af;
+  float: left;
+  height: 0;
+  pointer-events: none;
+}
+```
+
+### Class names
+
+| Name                                   | Where the extension adds it                                    | When                                                                                                                                        |
+| -------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data-placeholder` (attribute)         | the empty textblock at the cursor only                         | the cursor sits in an empty textblock, the resolved hint text is not empty, and the editor is editable or `showOnlyWhenEditable` is `false` |
+| `is-empty` (`emptyNodeClass`)          | that same textblock, and every empty ancestor wrapper above it | the same three conditions as `data-placeholder`                                                                                             |
+| `is-editor-empty` (`emptyEditorClass`) | the same nodes as `is-empty`, next to it                       | the same three conditions, and the whole document is empty                                                                                  |
+
+Target `[data-placeholder]`, not `.is-empty`. The extension adds the empty class to an empty list item or blockquote, but not the attribute. A `.is-empty::before { content: attr(data-placeholder) }` rule therefore paints an empty pseudo-element on those wrappers as well.
+
+The extension never adds `is-editor-empty` to the editor root, because the ancestor walk stops below the document node. A `.ProseMirror.is-editor-empty` selector matches nothing.
+
+To show the hint only while the document is fully empty, swap the selector of the rule above for the selector below:
+
+```css
+.ProseMirror .is-editor-empty[data-placeholder]::before {
+  content: attr(data-placeholder);
+  color: #9ca3af;
+  float: left;
+  height: 0;
+  pointer-events: none;
+}
+```
+
+Select the empty ancestor wrappers on their own. This rule dims an empty blockquote or list item. Replace the declaration as needed:
+
+```css
+.ProseMirror blockquote.is-empty,
+.ProseMirror li.is-empty {
+  opacity: 0.6;
+}
+```
+
+The extension has no focus option. To hide the hint while the editor has no focus, add this rule:
+
+```css
+.ProseMirror:not(:focus-within) [data-placeholder]::before {
+  content: none;
+}
+```
+
+## Collaborative editing
+
+A remote edit that leaves the local selection alone keeps the hint, and moves it with the document.
+
+The plugin rebuilds its decorations when a transaction changes the document or sets the selection. A Yjs update arrives as a document change, so the rebuild runs and the decoration follows the new position. A transaction that carries only metadata, such as an awareness ping, skips the rebuild and keeps the previous decoration set.
+
+The decoration is local to one editor view. It never enters the document, so it never syncs to another client, and each client sees the hint at its own cursor.
+
+The clean-room spec [cypress/e2e/external-edit.cy.ts](https://github.com/docs-plus/docs.plus/blob/main/extensions/extension-placeholder/cypress/e2e/external-edit.cy.ts) covers both shapes: text inserted elsewhere, and a paragraph inserted before the empty textblock.
+
+## Migrating from the built-in Placeholder
+
+Tiptap 3.x ships the built-in Placeholder from `@tiptap/extensions`, subpath `./placeholder`. `@tiptap/extension-placeholder` is the older name for the same extension.
+
+Swap the import and keep the same configuration. The options this package accepts carry the built-in's names and defaults.
+
+```diff
+- import { Placeholder } from '@tiptap/extensions'
++ import { Placeholder } from '@docs.plus/extension-placeholder'
+```
+
+Remove the built-in from the extensions array in the same change. Both register the name `placeholder`, so leaving both in place makes both decorate.
+
+| Built-in option        | This package                                                                                                                                                                       |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `placeholder`          | Same name, same default `'Write something …'`. The callback also receives `parentName` and `doc`.                                                                                  |
+| `emptyNodeClass`       | Same name, same default `'is-empty'`. The extension also adds it to every empty ancestor wrapper.                                                                                  |
+| `emptyEditorClass`     | Same name, same default `'is-editor-empty'`. Unchanged: the built-in also adds it to the decorated nodes.                                                                          |
+| `showOnlyWhenEditable` | Same name, same default `true`. Read at render time, so `editor.setEditable()` updates the hint and both classes at once.                                                          |
+| `showOnlyCurrent`      | No option. The extension decorates only the empty textblock at the cursor.                                                                                                         |
+| `includeChildren`      | No option needed. The extension adds `data-placeholder` to the empty textblock at the cursor inside a list item or blockquote too, and adds the empty class to its empty wrappers. |
+| `dataAttribute`        | No option. The attribute is always `data-placeholder`.                                                                                                                             |
+
+Five behavior differences remain after the swap:
+
+- **Cost.** The built-in scans every top-level block with `doc.descendants` on every editor update, and the whole tree when `includeChildren` is on. This package walks from the cursor up to the first non-empty ancestor.
+- **Rebuild timing.** The built-in re-evaluates the `placeholder` callback on every editor update. This package rebuilds only when a transaction changes the document or sets the selection.
+- **Empty hint.** A resolved hint of `''` removes the decoration and both classes here. The built-in still emits the classes.
+- **Document-depth selection.** ⌘A or Ctrl+A hides the hint here. The built-in keeps it.
+- **`hasAnchor`.** Always `true` here, because the extension decorates only the empty textblock at the cursor. The built-in passes `false` when `showOnlyCurrent: false` decorates a node away from the cursor.
+
+Class-based CSS keeps working, with one change: the extension now adds the empty class to an empty list item or blockquote as well. Add `[data-placeholder]` to the selector to reach only the textblock that holds the hint. See [Styling](#styling).
+
+Full breaking-change list: [CHANGELOG.md](https://github.com/docs-plus/docs.plus/blob/main/extensions/extension-placeholder/CHANGELOG.md).
+
+## TypeScript
+
+`dist/index.d.ts` exports three symbols, and the options in [Options](#options) are the whole API.
+
+Extension:
+
+- `Placeholder` — `Extension<PlaceholderOptions, any>`, registered under the name `placeholder`.
+
+Types:
+
+- `PlaceholderOptions` — the four option fields.
+- `PlaceholderRenderProps` — the argument the callback form of `placeholder` receives.
+
+Nothing else exists, so this README skips four sections:
+
+- No `addCommands`. `editor.commands` gains nothing, so there is no Commands section.
+- No `addKeyboardShortcuts` and no keydown handler. The extension binds no keys, so there is no Keyboard shortcuts section.
+- No `addStorage`. `editor.storage.placeholder` holds the empty object Tiptap creates for every extension.
+- No option and no attribute holds a URL, and the source calls no `window.open`, so there is no Security section.
+
+## Part of docs.plus
+
+This extension is built for and maintained by [docs.plus](https://docs.plus). docs.plus is a free, real-time collaboration tool that lets communities organize knowledge hierarchically, with a chat thread on every heading. docs.plus runs these packages from source in production, so every release is exercised there before it reaches npm.
+
+- Website: [docs.plus](https://docs.plus)
+- Project README: [docs-plus/docs.plus](https://github.com/docs-plus/docs.plus#readme)
+- Sibling extensions and recommended pairings: [extensions/README.md](https://github.com/docs-plus/docs.plus/blob/main/extensions/README.md)
+
+## Contributing
+
+Bug reports and PRs welcome. Setup, test commands, and the playground harness live in [CONTRIBUTING.md](https://github.com/docs-plus/docs.plus/blob/main/extensions/extension-placeholder/CONTRIBUTING.md).
+
+## License
+
+MIT — see [LICENSE](https://github.com/docs-plus/docs.plus/blob/main/LICENSE).

package/dist/index.cjs

@@ -0,0 +1,2 @@
+"use strict";var p=Object.defineProperty;var b=Object.getOwnPropertyDescriptor;var g=Object.getOwnPropertyNames;var N=Object.prototype.hasOwnProperty;var C=(e,r)=>{for(var o in r)p(e,o,{get:r[o],enumerable:!0})},D=(e,r,o,t)=>{if(r&&typeof r=="object"||typeof r=="function")for(let n of g(r))!N.call(e,n)&&n!==o&&p(e,n,{get:()=>r[n],enumerable:!(t=b(r,n))||t.enumerable});return e};var O=e=>D(p({},"__esModule",{value:!0}),e);var w={};C(w,{Placeholder:()=>P});module.exports=O(w);var a=require("@tiptap/core"),l=require("@tiptap/pm/state"),i=require("@tiptap/pm/view"),x=new l.PluginKey("placeholder");function E(e,r,o){let{$anchor:t}=e.selection;if(t.depth===0)return i.DecorationSet.empty;let n=t.parent;if(!n.type.isTextblock||!(0,a.isNodeEmpty)(n))return i.DecorationSet.empty;let s=t.before(t.depth),S=t.node(t.depth-1).type.name,c=typeof o.placeholder=="function"?o.placeholder({editor:r,node:n,pos:s,hasAnchor:!0,parentName:S,doc:e.doc}):o.placeholder;if(!c)return i.DecorationSet.empty;let h=[o.emptyNodeClass];(0,a.isNodeEmpty)(e.doc)&&h.push(o.emptyEditorClass);let m=h.join(" "),u=[i.Decoration.node(s,s+n.nodeSize,{class:m,"data-placeholder":c})];for(let d=t.depth-1;d>=1;d--){let y=t.node(d);if(!(0,a.isNodeEmpty)(y))break;let f=t.before(d);u.push(i.Decoration.node(f,f+y.nodeSize,{class:m}))}return i.DecorationSet.create(e.doc,u)}var P=a.Extension.create({name:"placeholder",addOptions(){return{emptyEditorClass:"is-editor-empty",emptyNodeClass:"is-empty",placeholder:"Write something \u2026",showOnlyWhenEditable:!0}},addProseMirrorPlugins(){let e=this.editor,r=this.options;return[new l.Plugin({key:x,state:{init(o,t){return E(t,e,r)},apply(o,t,n,s){return!o.docChanged&&!o.selectionSet?t:E(s,e,r)}},props:{decorations(o){return r.showOnlyWhenEditable&&!e.isEditable?null:this.getState(o)??null}}})]}});0&&(module.exports={Placeholder});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/placeholder.ts"],"sourcesContent":["export type { PlaceholderOptions, PlaceholderRenderProps } from './placeholder'\nexport { Placeholder } from './placeholder'\n","import type { Editor } from '@tiptap/core'\nimport { Extension, isNodeEmpty } from '@tiptap/core'\nimport type { Node as ProseMirrorNode } from '@tiptap/pm/model'\nimport type { EditorState, Transaction } from '@tiptap/pm/state'\nimport { Plugin, PluginKey } from '@tiptap/pm/state'\nimport { Decoration, DecorationSet } from '@tiptap/pm/view'\n\n/** Arguments passed to the `placeholder` callback when it is a function. */\nexport interface PlaceholderRenderProps {\n  editor: Editor\n  node: ProseMirrorNode\n  pos: number\n  hasAnchor: boolean\n  /** Parent node type name (e.g. 'doc', 'listItem', 'blockquote'). Safe during apply(). */\n  parentName: string\n  /** Doc that `pos` resolves against. Use this — `editor.state.doc` is stale during apply(). */\n  doc: ProseMirrorNode\n}\n\nexport interface PlaceholderOptions {\n  emptyEditorClass: string\n  emptyNodeClass: string\n  placeholder: ((props: PlaceholderRenderProps) => string) | string\n  showOnlyWhenEditable: boolean\n}\n\nconst PLACEHOLDER_KEY = new PluginKey('placeholder')\n\n/**\n * At most one placeholder decoration at the cursor's empty parent, plus\n * empty-class decorations on empty ancestor wrappers. Cost: O(depth).\n */\nfunction buildFromCursor(\n  state: EditorState,\n  editor: Editor,\n  options: PlaceholderOptions\n): DecorationSet {\n  const { $anchor } = state.selection\n  if ($anchor.depth === 0) return DecorationSet.empty\n\n  const node = $anchor.parent\n  if (!node.type.isTextblock || !isNodeEmpty(node)) return DecorationSet.empty\n\n  const pos = $anchor.before($anchor.depth)\n  const parentName = $anchor.node($anchor.depth - 1).type.name\n  const placeholderText =\n    typeof options.placeholder === 'function'\n      ? options.placeholder({ editor, node, pos, hasAnchor: true, parentName, doc: state.doc })\n      : options.placeholder\n\n  if (!placeholderText) return DecorationSet.empty\n\n  const classes = [options.emptyNodeClass]\n  if (isNodeEmpty(state.doc)) {\n    classes.push(options.emptyEditorClass)\n  }\n\n  const classStr = classes.join(' ')\n  const decorations: Decoration[] = [\n    Decoration.node(pos, pos + node.nodeSize, {\n      class: classStr,\n      'data-placeholder': placeholderText\n    })\n  ]\n\n  // Propagate empty class to ancestor wrappers (list items, blockquotes, etc.)\n  for (let d = $anchor.depth - 1; d >= 1; d--) {\n    const ancestor = $anchor.node(d)\n    if (!isNodeEmpty(ancestor)) break\n    const ancestorPos = $anchor.before(d)\n    decorations.push(\n      Decoration.node(ancestorPos, ancestorPos + ancestor.nodeSize, {\n        class: classStr\n      })\n    )\n  }\n\n  return DecorationSet.create(state.doc, decorations)\n}\n\n/**\n * Drop-in replacement for the built-in Placeholder with O(depth) cursor-based\n * state init/apply instead of the built-in's O(N) doc.descendants scan.\n * Decorates the empty node at the cursor plus empty ancestor wrappers —\n * inherently showOnlyCurrent + includeChildren.\n */\nexport const Placeholder = Extension.create<PlaceholderOptions>({\n  name: 'placeholder',\n\n  addOptions() {\n    return {\n      emptyEditorClass: 'is-editor-empty',\n      emptyNodeClass: 'is-empty',\n      placeholder: 'Write something …',\n      showOnlyWhenEditable: true\n    }\n  },\n\n  addProseMirrorPlugins() {\n    const editor = this.editor\n    const options = this.options\n\n    return [\n      new Plugin({\n        key: PLACEHOLDER_KEY,\n\n        state: {\n          init(_: unknown, state: EditorState): DecorationSet {\n            return buildFromCursor(state, editor, options)\n          },\n\n          apply(\n            tr: Transaction,\n            old: DecorationSet,\n            _oldState: EditorState,\n            newState: EditorState\n          ): DecorationSet {\n            // Decorations derive solely from doc + selection, so meta-only\n            // transactions (collab pings, plugin meta) cannot change them.\n            if (!tr.docChanged && !tr.selectionSet) return old\n\n            return buildFromCursor(newState, editor, options)\n          }\n        },\n\n        props: {\n          // Gate editability here, not in apply. `setEditable()` refreshes props via\n          // view.updateState without dispatching a transaction, so the placeholder\n          // toggles immediately when the editor flips to/from read-only.\n          decorations(state: EditorState): DecorationSet | null {\n            if (options.showOnlyWhenEditable && !editor.isEditable) return null\n            return this.getState(state) ?? null\n          }\n        }\n      })\n    ]\n  }\n})\n"],"mappings":"yaAAA,IAAAA,EAAA,GAAAC,EAAAD,EAAA,iBAAAE,IAAA,eAAAC,EAAAH,GCCA,IAAAI,EAAuC,wBAGvCC,EAAkC,4BAClCC,EAA0C,2BAqBpCC,EAAkB,IAAI,YAAU,aAAa,EAMnD,SAASC,EACPC,EACAC,EACAC,EACe,CACf,GAAM,CAAE,QAAAC,CAAQ,EAAIH,EAAM,UAC1B,GAAIG,EAAQ,QAAU,EAAG,OAAO,gBAAc,MAE9C,IAAMC,EAAOD,EAAQ,OACrB,GAAI,CAACC,EAAK,KAAK,aAAe,IAAC,eAAYA,CAAI,EAAG,OAAO,gBAAc,MAEvE,IAAMC,EAAMF,EAAQ,OAAOA,EAAQ,KAAK,EAClCG,EAAaH,EAAQ,KAAKA,EAAQ,MAAQ,CAAC,EAAE,KAAK,KAClDI,EACJ,OAAOL,EAAQ,aAAgB,WAC3BA,EAAQ,YAAY,CAAE,OAAAD,EAAQ,KAAAG,EAAM,IAAAC,EAAK,UAAW,GAAM,WAAAC,EAAY,IAAKN,EAAM,GAAI,CAAC,EACtFE,EAAQ,YAEd,GAAI,CAACK,EAAiB,OAAO,gBAAc,MAE3C,IAAMC,EAAU,CAACN,EAAQ,cAAc,KACnC,eAAYF,EAAM,GAAG,GACvBQ,EAAQ,KAAKN,EAAQ,gBAAgB,EAGvC,IAAMO,EAAWD,EAAQ,KAAK,GAAG,EAC3BE,EAA4B,CAChC,aAAW,KAAKL,EAAKA,EAAMD,EAAK,SAAU,CACxC,MAAOK,EACP,mBAAoBF,CACtB,CAAC,CACH,EAGA,QAAS,EAAIJ,EAAQ,MAAQ,EAAG,GAAK,EAAG,IAAK,CAC3C,IAAMQ,EAAWR,EAAQ,KAAK,CAAC,EAC/B,GAAI,IAAC,eAAYQ,CAAQ,EAAG,MAC5B,IAAMC,EAAcT,EAAQ,OAAO,CAAC,EACpCO,EAAY,KACV,aAAW,KAAKE,EAAaA,EAAcD,EAAS,SAAU,CAC5D,MAAOF,CACT,CAAC,CACH,CACF,CAEA,OAAO,gBAAc,OAAOT,EAAM,IAAKU,CAAW,CACpD,CAQO,IAAMG,EAAc,YAAU,OAA2B,CAC9D,KAAM,cAEN,YAAa,CACX,MAAO,CACL,iBAAkB,kBAClB,eAAgB,WAChB,YAAa,yBACb,qBAAsB,EACxB,CACF,EAEA,uBAAwB,CACtB,IAAMZ,EAAS,KAAK,OACdC,EAAU,KAAK,QAErB,MAAO,CACL,IAAI,SAAO,CACT,IAAKJ,EAEL,MAAO,CACL,KAAKgB,EAAYd,EAAmC,CAClD,OAAOD,EAAgBC,EAAOC,EAAQC,CAAO,CAC/C,EAEA,MACEa,EACAC,EACAC,EACAC,EACe,CAGf,MAAI,CAACH,EAAG,YAAc,CAACA,EAAG,aAAqBC,EAExCjB,EAAgBmB,EAAUjB,EAAQC,CAAO,CAClD,CACF,EAEA,MAAO,CAIL,YAAYF,EAA0C,CACpD,OAAIE,EAAQ,sBAAwB,CAACD,EAAO,WAAmB,KACxD,KAAK,SAASD,CAAK,GAAK,IACjC,CACF,CACF,CAAC,CACH,CACF,CACF,CAAC","names":["index_exports","__export","Placeholder","__toCommonJS","import_core","import_state","import_view","PLACEHOLDER_KEY","buildFromCursor","state","editor","options","$anchor","node","pos","parentName","placeholderText","classes","classStr","decorations","ancestor","ancestorPos","Placeholder","_","tr","old","_oldState","newState"]}

package/dist/index.d.cts

@@ -0,0 +1,29 @@
+import { Extension, Editor } from '@tiptap/core';
+import { Node } from '@tiptap/pm/model';
+
+/** Arguments passed to the `placeholder` callback when it is a function. */
+interface PlaceholderRenderProps {
+    editor: Editor;
+    node: Node;
+    pos: number;
+    hasAnchor: boolean;
+    /** Parent node type name (e.g. 'doc', 'listItem', 'blockquote'). Safe during apply(). */
+    parentName: string;
+    /** Doc that `pos` resolves against. Use this — `editor.state.doc` is stale during apply(). */
+    doc: Node;
+}
+interface PlaceholderOptions {
+    emptyEditorClass: string;
+    emptyNodeClass: string;
+    placeholder: ((props: PlaceholderRenderProps) => string) | string;
+    showOnlyWhenEditable: boolean;
+}
+/**
+ * Drop-in replacement for the built-in Placeholder with O(depth) cursor-based
+ * state init/apply instead of the built-in's O(N) doc.descendants scan.
+ * Decorates the empty node at the cursor plus empty ancestor wrappers —
+ * inherently showOnlyCurrent + includeChildren.
+ */
+declare const Placeholder: Extension<PlaceholderOptions, any>;
+
+export { Placeholder, type PlaceholderOptions, type PlaceholderRenderProps };

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import { Extension, Editor } from '@tiptap/core';
+import { Node } from '@tiptap/pm/model';
+
+/** Arguments passed to the `placeholder` callback when it is a function. */
+interface PlaceholderRenderProps {
+    editor: Editor;
+    node: Node;
+    pos: number;
+    hasAnchor: boolean;
+    /** Parent node type name (e.g. 'doc', 'listItem', 'blockquote'). Safe during apply(). */
+    parentName: string;
+    /** Doc that `pos` resolves against. Use this — `editor.state.doc` is stale during apply(). */
+    doc: Node;
+}
+interface PlaceholderOptions {
+    emptyEditorClass: string;
+    emptyNodeClass: string;
+    placeholder: ((props: PlaceholderRenderProps) => string) | string;
+    showOnlyWhenEditable: boolean;
+}
+/**
+ * Drop-in replacement for the built-in Placeholder with O(depth) cursor-based
+ * state init/apply instead of the built-in's O(N) doc.descendants scan.
+ * Decorates the empty node at the cursor plus empty ancestor wrappers —
+ * inherently showOnlyCurrent + includeChildren.
+ */
+declare const Placeholder: Extension<PlaceholderOptions, any>;
+
+export { Placeholder, type PlaceholderOptions, type PlaceholderRenderProps };

package/dist/index.js

@@ -0,0 +1,2 @@
+import{Extension as P,isNodeEmpty as d}from"@tiptap/core";import{Plugin as S,PluginKey as b}from"@tiptap/pm/state";import{Decoration as y,DecorationSet as s}from"@tiptap/pm/view";var g=new b("placeholder");function f(t,r,o){let{$anchor:e}=t.selection;if(e.depth===0)return s.empty;let n=e.parent;if(!n.type.isTextblock||!d(n))return s.empty;let i=e.before(e.depth),E=e.node(e.depth-1).type.name,l=typeof o.placeholder=="function"?o.placeholder({editor:r,node:n,pos:i,hasAnchor:!0,parentName:E,doc:t.doc}):o.placeholder;if(!l)return s.empty;let p=[o.emptyNodeClass];d(t.doc)&&p.push(o.emptyEditorClass);let c=p.join(" "),h=[y.node(i,i+n.nodeSize,{class:c,"data-placeholder":l})];for(let a=e.depth-1;a>=1;a--){let m=e.node(a);if(!d(m))break;let u=e.before(a);h.push(y.node(u,u+m.nodeSize,{class:c}))}return s.create(t.doc,h)}var N=P.create({name:"placeholder",addOptions(){return{emptyEditorClass:"is-editor-empty",emptyNodeClass:"is-empty",placeholder:"Write something \u2026",showOnlyWhenEditable:!0}},addProseMirrorPlugins(){let t=this.editor,r=this.options;return[new S({key:g,state:{init(o,e){return f(e,t,r)},apply(o,e,n,i){return!o.docChanged&&!o.selectionSet?e:f(i,t,r)}},props:{decorations(o){return r.showOnlyWhenEditable&&!t.isEditable?null:this.getState(o)??null}}})]}});export{N as Placeholder};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/placeholder.ts"],"sourcesContent":["import type { Editor } from '@tiptap/core'\nimport { Extension, isNodeEmpty } from '@tiptap/core'\nimport type { Node as ProseMirrorNode } from '@tiptap/pm/model'\nimport type { EditorState, Transaction } from '@tiptap/pm/state'\nimport { Plugin, PluginKey } from '@tiptap/pm/state'\nimport { Decoration, DecorationSet } from '@tiptap/pm/view'\n\n/** Arguments passed to the `placeholder` callback when it is a function. */\nexport interface PlaceholderRenderProps {\n  editor: Editor\n  node: ProseMirrorNode\n  pos: number\n  hasAnchor: boolean\n  /** Parent node type name (e.g. 'doc', 'listItem', 'blockquote'). Safe during apply(). */\n  parentName: string\n  /** Doc that `pos` resolves against. Use this — `editor.state.doc` is stale during apply(). */\n  doc: ProseMirrorNode\n}\n\nexport interface PlaceholderOptions {\n  emptyEditorClass: string\n  emptyNodeClass: string\n  placeholder: ((props: PlaceholderRenderProps) => string) | string\n  showOnlyWhenEditable: boolean\n}\n\nconst PLACEHOLDER_KEY = new PluginKey('placeholder')\n\n/**\n * At most one placeholder decoration at the cursor's empty parent, plus\n * empty-class decorations on empty ancestor wrappers. Cost: O(depth).\n */\nfunction buildFromCursor(\n  state: EditorState,\n  editor: Editor,\n  options: PlaceholderOptions\n): DecorationSet {\n  const { $anchor } = state.selection\n  if ($anchor.depth === 0) return DecorationSet.empty\n\n  const node = $anchor.parent\n  if (!node.type.isTextblock || !isNodeEmpty(node)) return DecorationSet.empty\n\n  const pos = $anchor.before($anchor.depth)\n  const parentName = $anchor.node($anchor.depth - 1).type.name\n  const placeholderText =\n    typeof options.placeholder === 'function'\n      ? options.placeholder({ editor, node, pos, hasAnchor: true, parentName, doc: state.doc })\n      : options.placeholder\n\n  if (!placeholderText) return DecorationSet.empty\n\n  const classes = [options.emptyNodeClass]\n  if (isNodeEmpty(state.doc)) {\n    classes.push(options.emptyEditorClass)\n  }\n\n  const classStr = classes.join(' ')\n  const decorations: Decoration[] = [\n    Decoration.node(pos, pos + node.nodeSize, {\n      class: classStr,\n      'data-placeholder': placeholderText\n    })\n  ]\n\n  // Propagate empty class to ancestor wrappers (list items, blockquotes, etc.)\n  for (let d = $anchor.depth - 1; d >= 1; d--) {\n    const ancestor = $anchor.node(d)\n    if (!isNodeEmpty(ancestor)) break\n    const ancestorPos = $anchor.before(d)\n    decorations.push(\n      Decoration.node(ancestorPos, ancestorPos + ancestor.nodeSize, {\n        class: classStr\n      })\n    )\n  }\n\n  return DecorationSet.create(state.doc, decorations)\n}\n\n/**\n * Drop-in replacement for the built-in Placeholder with O(depth) cursor-based\n * state init/apply instead of the built-in's O(N) doc.descendants scan.\n * Decorates the empty node at the cursor plus empty ancestor wrappers —\n * inherently showOnlyCurrent + includeChildren.\n */\nexport const Placeholder = Extension.create<PlaceholderOptions>({\n  name: 'placeholder',\n\n  addOptions() {\n    return {\n      emptyEditorClass: 'is-editor-empty',\n      emptyNodeClass: 'is-empty',\n      placeholder: 'Write something …',\n      showOnlyWhenEditable: true\n    }\n  },\n\n  addProseMirrorPlugins() {\n    const editor = this.editor\n    const options = this.options\n\n    return [\n      new Plugin({\n        key: PLACEHOLDER_KEY,\n\n        state: {\n          init(_: unknown, state: EditorState): DecorationSet {\n            return buildFromCursor(state, editor, options)\n          },\n\n          apply(\n            tr: Transaction,\n            old: DecorationSet,\n            _oldState: EditorState,\n            newState: EditorState\n          ): DecorationSet {\n            // Decorations derive solely from doc + selection, so meta-only\n            // transactions (collab pings, plugin meta) cannot change them.\n            if (!tr.docChanged && !tr.selectionSet) return old\n\n            return buildFromCursor(newState, editor, options)\n          }\n        },\n\n        props: {\n          // Gate editability here, not in apply. `setEditable()` refreshes props via\n          // view.updateState without dispatching a transaction, so the placeholder\n          // toggles immediately when the editor flips to/from read-only.\n          decorations(state: EditorState): DecorationSet | null {\n            if (options.showOnlyWhenEditable && !editor.isEditable) return null\n            return this.getState(state) ?? null\n          }\n        }\n      })\n    ]\n  }\n})\n"],"mappings":"AACA,OAAS,aAAAA,EAAW,eAAAC,MAAmB,eAGvC,OAAS,UAAAC,EAAQ,aAAAC,MAAiB,mBAClC,OAAS,cAAAC,EAAY,iBAAAC,MAAqB,kBAqB1C,IAAMC,EAAkB,IAAIH,EAAU,aAAa,EAMnD,SAASI,EACPC,EACAC,EACAC,EACe,CACf,GAAM,CAAE,QAAAC,CAAQ,EAAIH,EAAM,UAC1B,GAAIG,EAAQ,QAAU,EAAG,OAAON,EAAc,MAE9C,IAAMO,EAAOD,EAAQ,OACrB,GAAI,CAACC,EAAK,KAAK,aAAe,CAACX,EAAYW,CAAI,EAAG,OAAOP,EAAc,MAEvE,IAAMQ,EAAMF,EAAQ,OAAOA,EAAQ,KAAK,EAClCG,EAAaH,EAAQ,KAAKA,EAAQ,MAAQ,CAAC,EAAE,KAAK,KAClDI,EACJ,OAAOL,EAAQ,aAAgB,WAC3BA,EAAQ,YAAY,CAAE,OAAAD,EAAQ,KAAAG,EAAM,IAAAC,EAAK,UAAW,GAAM,WAAAC,EAAY,IAAKN,EAAM,GAAI,CAAC,EACtFE,EAAQ,YAEd,GAAI,CAACK,EAAiB,OAAOV,EAAc,MAE3C,IAAMW,EAAU,CAACN,EAAQ,cAAc,EACnCT,EAAYO,EAAM,GAAG,GACvBQ,EAAQ,KAAKN,EAAQ,gBAAgB,EAGvC,IAAMO,EAAWD,EAAQ,KAAK,GAAG,EAC3BE,EAA4B,CAChCd,EAAW,KAAKS,EAAKA,EAAMD,EAAK,SAAU,CACxC,MAAOK,EACP,mBAAoBF,CACtB,CAAC,CACH,EAGA,QAASI,EAAIR,EAAQ,MAAQ,EAAGQ,GAAK,EAAGA,IAAK,CAC3C,IAAMC,EAAWT,EAAQ,KAAKQ,CAAC,EAC/B,GAAI,CAAClB,EAAYmB,CAAQ,EAAG,MAC5B,IAAMC,EAAcV,EAAQ,OAAOQ,CAAC,EACpCD,EAAY,KACVd,EAAW,KAAKiB,EAAaA,EAAcD,EAAS,SAAU,CAC5D,MAAOH,CACT,CAAC,CACH,CACF,CAEA,OAAOZ,EAAc,OAAOG,EAAM,IAAKU,CAAW,CACpD,CAQO,IAAMI,EAActB,EAAU,OAA2B,CAC9D,KAAM,cAEN,YAAa,CACX,MAAO,CACL,iBAAkB,kBAClB,eAAgB,WAChB,YAAa,yBACb,qBAAsB,EACxB,CACF,EAEA,uBAAwB,CACtB,IAAMS,EAAS,KAAK,OACdC,EAAU,KAAK,QAErB,MAAO,CACL,IAAIR,EAAO,CACT,IAAKI,EAEL,MAAO,CACL,KAAKiB,EAAYf,EAAmC,CAClD,OAAOD,EAAgBC,EAAOC,EAAQC,CAAO,CAC/C,EAEA,MACEc,EACAC,EACAC,EACAC,EACe,CAGf,MAAI,CAACH,EAAG,YAAc,CAACA,EAAG,aAAqBC,EAExClB,EAAgBoB,EAAUlB,EAAQC,CAAO,CAClD,CACF,EAEA,MAAO,CAIL,YAAYF,EAA0C,CACpD,OAAIE,EAAQ,sBAAwB,CAACD,EAAO,WAAmB,KACxD,KAAK,SAASD,CAAK,GAAK,IACjC,CACF,CACF,CAAC,CACH,CACF,CACF,CAAC","names":["Extension","isNodeEmpty","Plugin","PluginKey","Decoration","DecorationSet","PLACEHOLDER_KEY","buildFromCursor","state","editor","options","$anchor","node","pos","parentName","placeholderText","classes","classStr","decorations","d","ancestor","ancestorPos","Placeholder","_","tr","old","_oldState","newState"]}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@docs.plus/extension-placeholder",
+  "version": "2.0.0",
+  "description": "A performance-optimized Tiptap placeholder extension using O(depth) cursor-based decoration",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "author": "Hossein Marzban",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://github.com/docs-plus/docs.plus/tree/main/extensions/extension-placeholder#readme",
+  "bugs": {
+    "url": "https://github.com/docs-plus/docs.plus/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/docs-plus/docs.plus",
+    "directory": "extensions/extension-placeholder"
+  },
+  "scripts": {
+    "build": "NODE_ENV=production bunx tsup",
+    "dev": "bunx tsup --watch",
+    "playground": "bun --hot docs-playground --entry ./test/playground/main.ts --port 5177",
+    "docs:screenshots": "bun run build && bunx start-server-and-test playground http://127.0.0.1:5177 'bunx cypress run --config specPattern=cypress/docs/**/*.cy.ts'",
+    "pretest": "bun run build",
+    "test": "bunx start-server-and-test playground http://127.0.0.1:5177 cypress:run",
+    "test:e2e": "bunx start-server-and-test playground http://127.0.0.1:5177 cypress:run",
+    "test:e2e:watch": "bunx start-server-and-test playground http://127.0.0.1:5177 cypress:open",
+    "cypress:run": "bunx cypress run",
+    "cypress:open": "bunx cypress open",
+    "typecheck": "tsc --noEmit",
+    "prepack": "bunx release-prepack",
+    "prepublishOnly": "bunx release-preflight"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "tiptap",
+    "tiptap extension",
+    "placeholder",
+    "rich-text-editor",
+    "prosemirror",
+    "docs.plus"
+  ],
+  "peerDependencies": {
+    "@tiptap/core": "^3.22.3",
+    "@tiptap/pm": "^3.22.3"
+  },
+  "devDependencies": {
+    "@docs.plus/playground": "0.0.0",
+    "@docs.plus/release-tooling": "0.1.0",
+    "@tiptap/core": "^3.22.3",
+    "@tiptap/pm": "^3.22.3",
+    "@tiptap/starter-kit": "^3.22.3",
+    "cypress": "^15.13.1",
+    "cypress-real-events": "^1.15.0",
+    "eslint": "^9.39.4",
+    "start-server-and-test": "^2.1.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}